feat(hooks): action + filter bus (WordPress-style) — closes #178

[tayebmokni]

Summary

Implements the in-process hook bus kernel that backs the plugin system per docs/02-plugin-system.md §5.

• Bus with RegisterAction / RegisterAsync / RegisterFilter, each returning an idempotent unsubscribe closure.
• Do(ctx, name, args...) dispatches an action; runs every handler in priority order (lower first; ties keep registration order); aggregates errors via errors.Join; recovers from panics so one bad listener doesn't drop the rest.
• ApplyFilters(ctx, name, value, args...) threads a value through the chain. A handler may stop early by returning ErrShortCircuit; non-short-circuit errors return the last accepted value with the error.
• RegisterAsync returns immediately; the handler runs in its own goroutine and its error is logged via slog rather than propagated.
• Lock-free reads: per-name handler chains live behind atomic.Pointer with copy-on-write mutation under a per-slot mutex. Registers are amortized at startup; dispatch is hot-path.
• Metrics hooks via a small Sink interface (Counter, Histogram) — default no-op, so packages/go/metrics can plug in later without inverting the dependency.
• Reentrance-safe: handlers may register/unregister hooks mid-dispatch. New handlers join the next dispatch, not the in-flight one.

No new external dependencies — stdlib only (sync, sync/atomic, log/slog, context, errors, sort, time).

Test plan

• go build ./hooks/...
• go vet ./hooks/...
• go test -race -count=1 -cover ./hooks/... — 100.0% statement coverage
• Action: register + fire + handler runs
• Multiple handlers in priority order (with tie-break by registration order)
• Filter chain transforms value through every handler
• Filter short-circuit via ErrShortCircuit (direct and fmt.Errorf("...: %w", ErrShortCircuit))
• Action error aggregation: all handlers run, errors join via errors.Join
• Async action returns immediately; handler runs in goroutine; Wait() synchronizes
• Async error is logged via slog, not returned to Do's caller
• Panic in sync action: logged, surfaced as *panicError, chain continues
• Panic in filter: logged, surfaced as *panicError, chain STOPS, last accepted value returned
• Panic in async action: logged, never crashes the bus
• Unsubscribe is idempotent (double-call is a no-op)
• Self-unsubscribe mid-dispatch is safe; later handlers still run; next dispatch sees the change
• Reentrant registration from inside a handler joins on the NEXT dispatch
• Concurrent register + fire + unregister: race detector clean
• Context propagation through both action and filter
• Metrics sink receives dispatch, error, panic, short-circuit, and duration callbacks

Closes

Closes #178

DCO

Signed-off-by: Claude (for tayebmokni) tayeb.mokni@gmail.com