HAR-412 · Analysis and recommendation

Notification Routing Overhaul

A team lead asked to stop deploy notifications for one project. There is no place to do that, so support tells them to create a sub-project. This is the anatomy of why — five layers of routing configuration, none of them editable by the person asking — and a model that replaces all five with one rule.

Current state

How routing is set today

Five layers, in the order they are applied. The ordering is not documented anywhere in the code — it is the emergent result of one SQL UNION, one Ruby filter loop, one snapshot write, and one client-side store.

Resolution path

Where the answer is actually decided

The critical stage is the fourth. Channel resolution runs once, on first open, and the result is written to entry_channel_link. Re-opening a digest does not re-resolve it — the code short-circuits on has_entries?. Every configuration change made after that point is invisible for the life of the digest.

Diagnosis

Why it reads as layered, and why results surprise people

The sentiment in the ticket is accurate, and it is not only about the number of layers. Several mechanisms actively teach people the wrong mental model.

Recommendation

One pipeline, two authorship tiers, one vocabulary

The five layers exist because two genuinely different questions are being answered with the same mechanism — an additive link row naming a specific channel id. Separate the questions and the layer count collapses on its own.

1. Make the channel kind the only vocabulary anyone chooses from

   channel_kind already exists, already has display labels, and is already what mute.kind matches on. Promote it: team leads and admins choose among Email, Chat, Webhook and Digest — four nouns, never 40 channel ids. Variant selection stays with Delivery, one tier down. This single change is what makes "stop the chat pings" a coherent request instead of a 9-row enumeration.

2. Two tables replace four

   One table answers which variant, one answers wanted or not. The permission table is scope-polymorphic, so adding the project tier HAR-412 asks for is a new scope value rather than a new layer, a new query branch and a new precedence question.

   tier_channel_policy      (tier_id, channel_kind, channel_id, is_default)
                            — Delivery owns. Names the variant a plan expects.
   
   channel_permission       (scope, scope_id, channel_kind, permission)
                              scope ∈ tier | workspace | project | event
                              permission ∈ allow | deny
                            — The only table any customer-facing screen writes.
   

   The existing 612,400 event_channel_link rows migrate mechanically to scope='event', permission='allow', so the catalog work already done is preserved rather than re-entered.

3. Resolve when the digest is served, not when it is first opened

   The ticket's requirement — a lead turns deploy pings off and they stop — cannot be met while resolution is a one-time snapshot. Two options, in order of preference: resolve on read in get-digest, which removes the snapshot entirely and matches how workspace_preference already behaves; or, as the smaller change, rebuild the snapshot on every open and on every routing save. Either way, channels and preferences finally follow the same rule, so the settings screen stops teaching two of them.

4. Ship it into the UI slot that already exists

   The project settings screen already has a Preferences card: a registry-driven checkbox list, unsaved-changes badge, save and undo, and a tooltip explaining that preferences can only be changed while the project is idle. Add a Channels card beside it with the same interaction contract, driven by the channel-kind registry instead of workspace_preference. Leads already know how this card behaves. Event-level overrides belong in the event catalog, not here.

5. Always show the effective value and its source

   Most of the reported confusion is unanswerable questions, not wrong behavior. Every surface that mentions channels should read like "Chat — Off, set on this project" or "Email — Delivery relay (EU), from your plan". That one presentational rule is what turns a precedence chain from a hidden mechanism into something a team lead can reason about, and it is worth shipping before any behavior changes at all.

6. Retire the dimensions that only look like controls

   Each of these is something a reasonable person believes governs behavior, and does not.

   • required / required_input — drop it, or give it real meaning as "this channel cannot be denied at a lower tier", which is a genuinely useful guarantee for compliance channels.
   • project.channel_rules.allow — delete it along with the whole column once the permission table lands.
   • enabled = true on channels the client cannot render — the Digest and Webhook defs are flagged enabled, but the client has no component for either; the digest is a separate scheduled job. Reconcile the flag against what the channel component can actually mount.

Direct answer

"Which current methods for defining routing are needed?"

The ticket's own open question, answered against what the code shows. The short form: keep all four tiers, but stop letting three of them add and one of them subtract.

Sequencing

How to land it

Ordered so that the first phase changes no behavior and still reduces support load, and the second phase closes HAR-412 without waiting for the full model.

A worked example for the Markset documentation. The system, the ticket and every identifier here are invented. Written in Markset and rendered by the reference implementation with a theme stylesheet.

Examples: all · Showcase · Strategy memo · Incident review · source