fix(eventbus): timer-drain hang + silent-drop observability (#112)

[intel352]

Fixes #112 — one real bug plus two observability gaps in modules/eventbus.

P1 (bug) — MemoryEventBus.Publish hang in deliveryMode: "timeout"

The legacy if !deadline.Stop() { <-deadline.C } drain blocks the publisher forever once the timer fires (on Go 1.23+ timer channels are unbuffered, so the unconditional re-receive never returns). Replaced with the race-free non-blocking drain, covering both the timer-fired and ctx-cancelled exit branches. Kept inline (not defer) because the block is inside a per-subscriber for loop.

P2 (observability) — CustomMemoryEventBus dropped silently

Added deliveredCount/droppedCount + Stats() mirroring MemoryEventBus. Also changed EngineRouter.CollectStats/CollectPerEngineStats to dispatch over a new statsProvider interface instead of type-asserting the concrete *MemoryEventBus, so the custom engine (and any future stats-bearing engine) participates in module.Stats()/PerEngineStats(). DurableMemoryEventBus.Stats() has a single-value return and intentionally does not satisfy the interface (it never drops).

P3 (observability) — Unsubscribe/Stop abandoned buffered events uncounted

Both engines now count events still buffered in a subscriber channel as dropped on handler-goroutine exit (drainSubscription, run via defer so no exit path skips it), plus the dequeued-but-cancelled event. MemoryEventBus.Stop additionally drains the worker pool after wg.Wait() (race-free: all senders/receivers are wg-tracked and have exited) so abandoned async tasks are counted — closing the async conservation gap. CustomMemoryEventBus gained the WaitGroup + finished-channel shutdown synchronization the standard engine already had, so Stop waits for handlers to drain and Stats() is final on return.

Contract: at-most-once delivery across teardown — delivered + dropped == enqueued once publishers quiesce. Corrected the false "processes all in-flight events" Stop doc comments in eventbus.go and module.go. Decision recorded in decisions/0001-eventbus-at-most-once-teardown.md.

Process

• Design + adversarial-design-review (2 Critical + 4 Important found and resolved across rev 1→2): docs/plans/2026-05-28-eventbus-112-fix.md. The async-workerPool conservation gap (C1) and the dequeued-cancelled accounting hole (C2) were both caught at design time.
• Adversarial code review of the implementation: PASS, zero Critical.
• TDD. New tests: issue112_memory_test.go, issue112_custom_test.go (timer-hang guard, sync + async conservation across Unsubscribe and Stop, custom Stats, router statsProvider wiring).

Regression-invariant proof (timer hang, P1)

With fix reverted:
$ go test -race -run TestIssue112_TimeoutModePublishDoesNotHang
  --- FAIL: TestIssue112_TimeoutModePublishDoesNotHang (3.00s)
      Publish hung in timeout delivery mode (issue #112 P1): timer-drain deadlock

With fix applied:
$ go test -race -run TestIssue112_TimeoutModePublishDoesNotHang
  --- PASS: TestIssue112_TimeoutModePublishDoesNotHang (0.16s)

The conservation tests showed the same RED→GREEN: pre-fix delivered+dropped was 1/6 (Unsubscribe) and 2/30 (async Stop — 28 events lost in the worker pool); post-fix both reconcile exactly.

Verification

• cd modules/eventbus && go test -race ./... → ok (25.9s)
• gofmt clean, go vet clean, golangci-lint run → 0 issues

Closes #112.

[github-actions]

📋 API Contract Changes Summary

✅ No breaking changes detected - only additions and non-breaking modifications

Changed Components:

Core Framework

Contract diff saved to artifacts/diffs/core.json

Module: auth

Contract diff saved to artifacts/diffs/auth.json

Module: cache

Contract diff saved to artifacts/diffs/cache.json

Module: database

Contract diff saved to artifacts/diffs/database.json

Module: eventbus

Contract diff saved to artifacts/diffs/eventbus.json

Module: jsonschema

Contract diff saved to artifacts/diffs/jsonschema.json

Module: letsencrypt

Contract diff saved to artifacts/diffs/letsencrypt.json

Module: reverseproxy

Contract diff saved to artifacts/diffs/reverseproxy.json

Artifacts

📁 Full contract diffs and JSON artifacts are available in the workflow artifacts.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!