registerHook accepts event names the engine never dispatches — read filters on beforeFindOne/beforeCount silently never run

[hotlong]

Problem

engine.registerHook(event, handler) accepts an event name the engine never dispatches. It logs a warning, registers the handler anyway, and the handler silently never runs.

The engine dispatches beforeFind / afterFind and the insert / update / delete pairs. beforeFind covers both find and findOne. count() and aggregate() dispatch no hook: they run through the middleware chain only, with the query AST on the operation context.

A downstream consumer registered read filters on beforeFindOne and beforeCount, expecting them to scope single-record reads and list totals. They sat inert through every boot, with about 40 "never dispatches" warnings per boot. The effect:

• Single-record reads were still filtered, because beforeFind covers findOne.
• count was not. A limited list returned a total counting rows the caller could not see.
• aggregate was not either. A groupBy query was not narrowed by the filter at all.

Proposal

1. Refuse at registration when the event is outside the dispatchable set, in line with ADR-0078 ("no silently inert metadata"). At minimum, make the warning an error in strict or test mode.
2. Name the seam in the message. For beforeCount and beforeFindOne specifically, say that beforeFind already covers findOne, and that count / aggregate filtering belongs in middleware (operation: 'count' | 'aggregate').
3. Document in the hook reference that read filters written as hooks do not apply to count / aggregate, and show the middleware equivalent.

Acceptance

• Registering an undispatchable event fails loudly: it throws, or at least fails in strict mode.
• A test covers each event name that the engine exposes but never dispatches.
• The hook documentation lists which operations each event covers.

[os-musk]

Triage: lands on the engine's hook registry (engine.registerHook / the dispatch sites) ⇒ domain:engine; type Bug; priority:p2; pm:queue. security applied — see the trigger below.

Why Bug and not a Task

registerHook accepts a declaration the engine never honours: it warns, registers anyway, and the handler silently never runs. That is declared ≠ enforced on an authorable seam, and the card cites the right governing text — ADR-0078, 「no silently inert metadata」. ⇒ the existing behaviour is a contract violation, ⛔ not a missing feature.

p2 — with the p1 trigger written out, because the gap is a data-visibility one

⭐ The sharp half is not that the handler is inert; it is which operations silently escape the filter. Measured by the consumer:

• findOne was filtered — beforeFind covers it, so the author's mistake was harmless there;
• count was not ⇒ a limited list returned a total counting rows the caller could not see;
• aggregate was not ⇒ a groupBy was not narrowed at all.

⇒ an author who writes a read filter as a hook gets one silently unfiltered aggregate surface and one leaking total. ⛔ That is not a cosmetic warning.

p2 rather than p1, on three readings and ⛔ not on comfort: the engine does warn (~40 lines per boot — noisy, ⛔ not silent); the primary record-read path is filtered, so record bodies do not escape; and what leaks is counts and groupings, ⛔ not rows.

⚠️ Escalation trigger: if anyone measures the unfiltered count / aggregate crossing an ORGANIZATION boundary — a total or a groupBy bucket including another tenant's rows — this is priority:p1 on that reading alone. ⛔ The card does not claim it and I have ⛔ not measured it; the consumer's filters were scope filters, so it is a live question, not a rhetorical one.

⛔ The fence that decides whether this is one card or two

The proposal has three parts and only the first two are this card:

1. ✅ Refuse at registration when the event is outside the dispatchable set (throw, or at minimum fail in strict/test mode). That is the ADR-0078 repair.
2. ✅ Name the seam in the message — for beforeCount / beforeFindOne specifically: beforeFind already covers findOne, and count / aggregate filtering belongs in middleware (operation: 'count' | 'aggregate'). ⭐ This is the part that would have saved the consumer, and it is cheap.
3. ⚠️ Docs — the hook reference listing which operations each event covers. Lands in content/docs/** ⇒ domain:devx, ⛔ not this lane. ⇒ if the round cannot land it inside domain:engine's file surface, file it as a follow-up rather than widening the PR.

⛔ Out of scope, and ⛔ do not drift into it: making count / aggregate dispatch hooks. That would change the engine's dispatch contract and the accept set of what a hook may intercept — a published-surface widening, and a different, much larger card. This card makes the refusal honest; it does ⛔ not add the missing dispatch.

⚠️ And the acceptance criterion the card writes is the right one to hold: a test per event name the engine exposes but never dispatches. ⇒ the population must be enumerated from the dispatch sites, not from a hand-written list — a hand-written list is the same failure one layer up.

_{分诊席位 · session_015WpYyzhX8x2kEhouLBidt8 · R+182 · 2026-09-12T03:02Z · 本评论来自分诊座位}

---

Generated by Claude Code