@strav/broadcast 1.0.0-alpha.25

package/README.md

@@ -0,0 +1,33 @@
+# @strav/broadcast
+
+In-process and multi-node pub/sub for Strav 1.0. Powers SSE endpoints (`router.sse(...)` in `@strav/http`) and the broadcast notification channel (`@strav/notification/broadcast`). Apps inject the abstract `Broadcaster` token; the provider in the container picks the concrete driver — `MemoryBroadcaster` for single-node dev, `PostgresBroadcaster` for multi-node deployments.
+
+```ts
+import { Broadcaster } from '@strav/broadcast'
+
+@inject()
+class OrdersController {
+  constructor(private readonly broadcaster: Broadcaster) {}
+
+  async pay(req: Request): Promise<Response> {
+    const order = await this.orders.markPaid(req)
+    await this.broadcaster.publish(`private-orders.${order.tenantId}`, {
+      id: order.eventId,
+      event: 'order.paid',
+      data: { orderId: order.id, amount: order.amountCents },
+    })
+    return new Response(null, { status: 204 })
+  }
+}
+```
+
+Canonical docs live in [`docs/broadcast/README.md`](../../docs/broadcast/README.md).
+
+## What ships
+
+| Driver | Subpath | Notes |
+|---|---|---|
+| Memory | `@strav/broadcast` (root) + `@strav/broadcast/memory` | In-process pub/sub. Single-node only. Bounded per-subscription buffer with overflow hooks. |
+| Postgres | `@strav/broadcast/postgres` | Polling-ledger backplane (`strav_broadcast_events` table). Multi-node. ~250ms p50 latency at default polling interval. |
+
+Per-channel authorization is built into the base class — register exact names or trailing-wildcard patterns (`'private-orders.*'`) via `broadcaster.authorize(pattern, fn)`. Channels with the `private-` or `presence-` prefix are denied by default unless an authorizer says yes.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@strav/broadcast",
+  "version": "1.0.0-alpha.25",
+  "description": "Strav broadcast / pub-sub primitive — Broadcaster interface + MemoryBroadcaster (in-process) + PostgresBroadcaster (polling-ledger backplane) + per-channel authorization. Pairs with @strav/http's router.sse and @strav/notification/broadcast.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./memory": "./src/drivers/memory/index.ts",
+    "./postgres": "./src/drivers/postgres/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@strav/kernel": "1.0.0-alpha.25"
+  },
+  "peerDependencies": {
+    "@strav/database": "1.0.0-alpha.25",
+    "@types/bun": ">=1.3.14"
+  },
+  "peerDependenciesMeta": {
+    "@strav/database": {
+      "optional": true
+    }
+  },
+  "devDependencies": null
+}

package/src/broadcast_error.ts

@@ -0,0 +1,61 @@
+/**
+ * Typed error hierarchy. Same shape as `@strav/notification` — base
+ * `BroadcastError` extending `StravError`, narrower subclasses with
+ * stable `code`s apps branch on.
+ */
+
+import { StravError } from '@strav/kernel'
+
+interface BroadcastErrorOptions {
+  code?: string
+  status?: number
+  context?: Record<string, unknown>
+  cause?: unknown
+}
+
+export class BroadcastError extends StravError {
+  constructor(message: string, options: BroadcastErrorOptions = {}) {
+    super(
+      message,
+      { code: options.code ?? 'broadcast.error', status: options.status ?? 500 },
+      {
+        ...(options.context ? { context: options.context } : {}),
+        ...(options.cause !== undefined ? { cause: options.cause } : {}),
+      },
+    )
+  }
+}
+
+export class BroadcastConfigError extends BroadcastError {
+  constructor(message: string, options: { context?: Record<string, unknown> } = {}) {
+    super(message, {
+      code: 'broadcast.config',
+      status: 500,
+      ...(options.context ? { context: options.context } : {}),
+    })
+  }
+}
+
+export class BroadcastPublishError extends BroadcastError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
+    super(message, {
+      code: 'broadcast.publish',
+      status: 502,
+      ...(options.context ? { context: options.context } : {}),
+      ...(options.cause !== undefined ? { cause: options.cause } : {}),
+    })
+  }
+}
+
+export class BroadcastUnauthorizedError extends BroadcastError {
+  constructor(message: string, options: { context?: Record<string, unknown> } = {}) {
+    super(message, {
+      code: 'broadcast.unauthorized',
+      status: 403,
+      ...(options.context ? { context: options.context } : {}),
+    })
+  }
+}

package/src/broadcast_provider.ts

@@ -0,0 +1,62 @@
+/**
+ * `BroadcastProvider` — registers a `MemoryBroadcaster` under the
+ * `Broadcaster` token by default.
+ *
+ * Apps that want the Postgres backplane swap providers:
+ *
+ *   import { BroadcastProvider } from '@strav/broadcast'
+ *   import { PostgresBroadcastProvider } from '@strav/broadcast/postgres'
+ *
+ *   providers: [
+ *     ...,
+ *     new PostgresBroadcastProvider(),    // instead of BroadcastProvider
+ *   ]
+ *
+ * Both providers register under the same `Broadcaster` token, so app
+ * code injecting `Broadcaster` doesn't change between dev and prod.
+ *
+ * Eager singleton — the constructor runs at register-time so config
+ * errors surface at boot rather than first `publish()`.
+ */
+
+import { type Application, ConfigRepository, ServiceProvider } from '@strav/kernel'
+import { Broadcaster } from './broadcaster.ts'
+import {
+  MemoryBroadcaster,
+  type MemoryBroadcasterOptions,
+} from './drivers/memory/memory_broadcaster.ts'
+
+export interface MemoryBroadcastConfig extends MemoryBroadcasterOptions {
+  driver: 'memory'
+}
+
+export class BroadcastProvider extends ServiceProvider {
+  override readonly name = 'broadcast'
+  override readonly dependencies = ['config']
+
+  override register(app: Application): void {
+    app.singleton(Broadcaster, (c) => {
+      const cfg = c.resolve(ConfigRepository).get('broadcast') as MemoryBroadcastConfig | undefined
+      // Default to memory with no overrides if the app didn't configure
+      // anything — broadcast is opt-in; explicit config only buys you
+      // overrides. Apps that don't use broadcast simply never inject
+      // the token.
+      return new MemoryBroadcaster(
+        cfg !== undefined
+          ? {
+              ...(cfg.maxBufferSize !== undefined ? { maxBufferSize: cfg.maxBufferSize } : {}),
+              ...(cfg.onOverflow !== undefined ? { onOverflow: cfg.onOverflow } : {}),
+            }
+          : {},
+      )
+    })
+  }
+
+  override async boot(app: Application): Promise<void> {
+    app.resolve(Broadcaster)
+  }
+
+  override async shutdown(app: Application): Promise<void> {
+    await app.resolve(Broadcaster).close()
+  }
+}

package/src/broadcaster.ts

@@ -0,0 +1,82 @@
+/**
+ * `Broadcaster` — the abstract base that every driver extends and apps
+ * inject via the container.
+ *
+ *   - `publish(channel, event)` — fan-out an event to every subscriber.
+ *     Returns once the driver has accepted the publish (for memory:
+ *     synchronously; for postgres: after the INSERT commits).
+ *   - `subscribe(channel)` — open an `AsyncIterable<BroadcastEvent>`
+ *     that yields events until closed via `unsubscribe()` (or by
+ *     breaking out of the `for await` loop).
+ *   - `authorize(pattern, fn)` — register a per-channel authorization
+ *     check. SSE handlers + the notification driver call
+ *     `authorizeFor(channel, subject)` before opening a subscription
+ *     on behalf of a user.
+ *   - `close()` — release driver resources. Optional override; the
+ *     `BroadcastProvider.shutdown()` hook calls it.
+ *
+ * The class is abstract so it serves as the container token —
+ * `app.singleton(Broadcaster, factory)` binds the concrete driver,
+ * `container.resolve(Broadcaster)` returns it. Same pattern as
+ * `Database` / `Logger`.
+ *
+ * Multi-driver routing is not in scope — broadcast is typically one
+ * backplane per app (memory in dev, postgres in prod). Apps that want
+ * to mix wire two `Broadcaster` instances behind named tokens.
+ */
+
+import {
+  type ChannelAuthorizationResult,
+  type ChannelAuthorizer,
+  ChannelAuthorizerRegistry,
+  normalizeAuthorizerResult,
+} from './channel_authorizer.ts'
+import type { BroadcastEvent, BroadcastSubscription } from './types.ts'
+
+// Non-abstract so the class can be used as a container token —
+// `app.singleton(Broadcaster, factory)`. Subclasses MUST override
+// `publish` and `subscribe`; the defaults throw to surface forgotten
+// overrides during development. Same trade-off as `kernel`'s `Logger`.
+export class Broadcaster {
+  protected readonly authorizers = new ChannelAuthorizerRegistry()
+
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  publish(channel: string, event: BroadcastEvent): Promise<void> {
+    throw new Error('Broadcaster.publish must be overridden by the driver subclass.')
+  }
+  // biome-ignore lint/correctness/noUnusedFunctionParameters: subclass contract
+  subscribe(channel: string): BroadcastSubscription {
+    throw new Error('Broadcaster.subscribe must be overridden by the driver subclass.')
+  }
+
+  authorize(pattern: string, fn: ChannelAuthorizer): void {
+    this.authorizers.register(pattern, fn)
+  }
+
+  /**
+   * Resolve a registered authorizer against `subject` for `channel`.
+   *
+   * Default policy when no authorizer matches:
+   *   - Channels with the `private-` or `presence-` prefix → denied
+   *     (Echo / Pusher convention; opt in by registering an
+   *     authorizer for the pattern).
+   *   - Everything else → allowed.
+   *
+   * Returns the structured `ChannelAuthorizationResult` — never
+   * throws on denial. Callers (SSE handler, notification driver)
+   * branch on `result.authorized`.
+   */
+  async authorizeFor(channel: string, subject: unknown): Promise<ChannelAuthorizationResult> {
+    const matched = this.authorizers.match(channel)
+    if (matched !== undefined) {
+      return normalizeAuthorizerResult(await matched(channel, subject))
+    }
+    if (channel.startsWith('private-') || channel.startsWith('presence-')) {
+      return { authorized: false }
+    }
+    return { authorized: true }
+  }
+
+  /** Optional resource cleanup. Default implementation is a no-op. */
+  async close(): Promise<void> {}
+}

package/src/channel_authorizer.ts

@@ -0,0 +1,81 @@
+/**
+ * Per-channel authorization.
+ *
+ * A `ChannelAuthorizer` decides whether a subject — typically the
+ * authenticated user, but any opaque value works — may subscribe to a
+ * named channel. Authorizers are matched literally first, then by
+ * pattern (`presence-room-*`); the first match wins. The default
+ * policy when no authorizer is registered is open / public (matching
+ * the in-process broadcast semantics — there's no auth across SSE
+ * connections by default; apps opt in).
+ *
+ * The function may return either a boolean (allowed?) or a richer
+ * `ChannelAuthorizationResult` carrying presence metadata that the
+ * caller (typically the SSE handler) embeds in the initial event
+ * stream. This mirrors Laravel Echo / Pusher conventions.
+ */
+
+export interface ChannelAuthorizationResult {
+  authorized: boolean
+  /**
+   * Optional structured metadata about the subject — surfaces on
+   * presence channels (e.g. `{ id: 'u_1', name: 'Alice' }`). The
+   * caller decides what to do with it; broadcasters themselves treat
+   * it as opaque.
+   */
+  presence?: Record<string, unknown>
+}
+
+export type ChannelAuthorizer = (
+  channel: string,
+  subject: unknown,
+) => boolean | ChannelAuthorizationResult | Promise<boolean | ChannelAuthorizationResult>
+
+/**
+ * Channel-name registry — used by `Broadcaster.authorize(pattern, fn)`.
+ * Supports exact names (`'orders.42'`) and trailing-wildcard patterns
+ * (`'orders.*'`, `'presence-room-*'`). No regex; the wildcard is a
+ * single `*` at the end. Keeps the implementation tight and avoids
+ * regex-injection footguns.
+ */
+export class ChannelAuthorizerRegistry {
+  private readonly exact = new Map<string, ChannelAuthorizer>()
+  private readonly prefixes: Array<{ prefix: string; fn: ChannelAuthorizer }> = []
+
+  register(pattern: string, fn: ChannelAuthorizer): void {
+    if (pattern.endsWith('*')) {
+      this.prefixes.push({ prefix: pattern.slice(0, -1), fn })
+      // Longer prefixes first → "orders.special.*" wins over "orders.*".
+      this.prefixes.sort((a, b) => b.prefix.length - a.prefix.length)
+      return
+    }
+    this.exact.set(pattern, fn)
+  }
+
+  /** Resolve the authorizer matching `channel`, or `undefined`. */
+  match(channel: string): ChannelAuthorizer | undefined {
+    const direct = this.exact.get(channel)
+    if (direct !== undefined) return direct
+    for (const { prefix, fn } of this.prefixes) {
+      if (channel.startsWith(prefix)) return fn
+    }
+    return undefined
+  }
+
+  clear(): void {
+    this.exact.clear()
+    this.prefixes.length = 0
+  }
+}
+
+/**
+ * Normalise an authorizer's return value to the canonical
+ * `ChannelAuthorizationResult` shape. Boolean returns become
+ * `{ authorized: bool }`; the structured form passes through.
+ */
+export function normalizeAuthorizerResult(
+  result: boolean | ChannelAuthorizationResult,
+): ChannelAuthorizationResult {
+  if (typeof result === 'boolean') return { authorized: result }
+  return result
+}

package/src/drivers/memory/index.ts

@@ -0,0 +1,4 @@
+export {
+  MemoryBroadcaster,
+  type MemoryBroadcasterOptions,
+} from './memory_broadcaster.ts'

package/src/drivers/memory/memory_broadcaster.ts

@@ -0,0 +1,151 @@
+/**
+ * `MemoryBroadcaster` — in-process pub/sub.
+ *
+ * Subscribers register a per-channel buffer; `publish` walks the
+ * buffer list, pushes the event onto each, and resolves any pending
+ * `next()` awaiters. Backpressure is bounded — buffers cap at
+ * `maxBufferSize` (default 1000), and the oldest event is dropped
+ * when the cap is hit. Apps that need stricter backpressure register
+ * an `onOverflow` handler at construction time.
+ *
+ * Single-process only. Apps deploying more than one node use
+ * `PostgresBroadcaster` (or write their own driver against Redis /
+ * NATS / etc.).
+ */
+
+import { Broadcaster } from '../../broadcaster.ts'
+import type { BroadcastEvent, BroadcastSubscription } from '../../types.ts'
+
+export interface MemoryBroadcasterOptions {
+  /**
+   * Maximum events buffered per subscription before the oldest is
+   * dropped. Tune higher if subscribers can pause for long stretches;
+   * tune lower to surface back-pressure faster. Default `1000`.
+   */
+  maxBufferSize?: number
+  /**
+   * Called when a subscription's buffer overflows and an event is
+   * dropped. Apps wire telemetry / metrics here. Default: silent.
+   */
+  onOverflow?: (channel: string, droppedEvent: BroadcastEvent) => void
+}
+
+interface MemorySubscriberState {
+  channel: string
+  buffer: BroadcastEvent[]
+  /** Resolves the consumer's pending `next()` call, if any. */
+  pendingResolve: ((result: IteratorResult<BroadcastEvent>) => void) | undefined
+  closed: boolean
+}
+
+export class MemoryBroadcaster extends Broadcaster {
+  private readonly subscribers = new Map<string, Set<MemorySubscriberState>>()
+  private readonly maxBufferSize: number
+  private readonly onOverflow: ((channel: string, event: BroadcastEvent) => void) | undefined
+
+  constructor(options: MemoryBroadcasterOptions = {}) {
+    super()
+    this.maxBufferSize = options.maxBufferSize ?? 1000
+    this.onOverflow = options.onOverflow
+  }
+
+  override async publish(channel: string, event: BroadcastEvent): Promise<void> {
+    const set = this.subscribers.get(channel)
+    if (set === undefined) return
+    for (const sub of set) {
+      this.deliver(sub, event)
+    }
+  }
+
+  override subscribe(channel: string): BroadcastSubscription {
+    const state: MemorySubscriberState = {
+      channel,
+      buffer: [],
+      pendingResolve: undefined,
+      closed: false,
+    }
+    let set = this.subscribers.get(channel)
+    if (set === undefined) {
+      set = new Set()
+      this.subscribers.set(channel, set)
+    }
+    set.add(state)
+
+    const detach = (): void => {
+      if (state.closed) return
+      state.closed = true
+      const s = this.subscribers.get(channel)
+      if (s !== undefined) {
+        s.delete(state)
+        if (s.size === 0) this.subscribers.delete(channel)
+      }
+      if (state.pendingResolve !== undefined) {
+        const resolve = state.pendingResolve
+        state.pendingResolve = undefined
+        resolve({ value: undefined, done: true })
+      }
+    }
+
+    const subscription: BroadcastSubscription = {
+      [Symbol.asyncIterator](): AsyncIterableIterator<BroadcastEvent> {
+        return subscription
+      },
+      async next(): Promise<IteratorResult<BroadcastEvent>> {
+        if (state.closed && state.buffer.length === 0) {
+          return { value: undefined, done: true }
+        }
+        const buffered = state.buffer.shift()
+        if (buffered !== undefined) return { value: buffered, done: false }
+        return new Promise<IteratorResult<BroadcastEvent>>((resolve) => {
+          state.pendingResolve = resolve
+        })
+      },
+      async return(): Promise<IteratorResult<BroadcastEvent>> {
+        detach()
+        return { value: undefined, done: true }
+      },
+      async unsubscribe(): Promise<void> {
+        detach()
+      },
+    }
+    return subscription
+  }
+
+  override async close(): Promise<void> {
+    for (const set of this.subscribers.values()) {
+      for (const sub of set) {
+        sub.closed = true
+        if (sub.pendingResolve !== undefined) {
+          const resolve = sub.pendingResolve
+          sub.pendingResolve = undefined
+          resolve({ value: undefined, done: true })
+        }
+      }
+    }
+    this.subscribers.clear()
+  }
+
+  /** Snapshot of subscriber count per channel — diagnostics / tests. */
+  subscriberCount(channel: string): number {
+    return this.subscribers.get(channel)?.size ?? 0
+  }
+
+  private deliver(state: MemorySubscriberState, event: BroadcastEvent): void {
+    if (state.closed) return
+    // Fast path — consumer is waiting on next().
+    if (state.pendingResolve !== undefined) {
+      const resolve = state.pendingResolve
+      state.pendingResolve = undefined
+      resolve({ value: event, done: false })
+      return
+    }
+    // Slow path — buffer + cap.
+    if (state.buffer.length >= this.maxBufferSize) {
+      const dropped = state.buffer.shift()
+      if (dropped !== undefined && this.onOverflow !== undefined) {
+        this.onOverflow(state.channel, dropped)
+      }
+    }
+    state.buffer.push(event)
+  }
+}

package/src/drivers/postgres/apply_broadcast_migration.ts

@@ -0,0 +1,34 @@
+/**
+ * `applyBroadcastMigration` — emit DDL for the
+ * `strav_broadcast_events` ledger plus the two indexes the
+ * `PostgresBroadcaster` relies on:
+ *
+ *   - `id` PK (created by the `bigSerial` column) — the poller's cursor.
+ *   - `created_at` index — used by the retention sweep.
+ *
+ * Apps register `broadcastEventSchema` with their `SchemaRegistry`
+ * and call this helper from a migration's `up`:
+ *
+ *   await applyBroadcastMigration(db, { registry })
+ *
+ * Mirrors `applyNotificationMigration` from `@strav/notification/database`.
+ */
+
+import { type DatabaseExecutor, emitCreateTable, type SchemaRegistry } from '@strav/database'
+import { broadcastEventSchema } from './broadcast_event_schema.ts'
+
+export interface ApplyBroadcastMigrationOptions {
+  registry: SchemaRegistry
+}
+
+export async function applyBroadcastMigration(
+  db: DatabaseExecutor,
+  options: ApplyBroadcastMigrationOptions,
+): Promise<void> {
+  const { registry } = options
+  await db.execute(emitCreateTable(broadcastEventSchema, { registry }).sql)
+  await db.execute(
+    `CREATE INDEX IF NOT EXISTS "idx_strav_broadcast_events_created_at"
+     ON "${broadcastEventSchema.name}" ("created_at")`,
+  )
+}

package/src/drivers/postgres/broadcast_event_schema.ts

@@ -0,0 +1,41 @@
+/**
+ * `strav_broadcast_events` schema — the backing ledger for
+ * `PostgresBroadcaster`.
+ *
+ * Append-only event log. Each `publish()` INSERTs one row; the
+ * shared per-process poller runs `SELECT * FROM strav_broadcast_events
+ * WHERE id > $lastId ORDER BY id` on a configurable interval and
+ * fanouts new rows to in-process subscribers.
+ *
+ * Columns:
+ *   - `id` (bigSerial PK) — monotonically increasing; the poller's
+ *     cursor. Big enough that we never wrap.
+ *   - `channel` (text) — routing key.
+ *   - `event_name` (text) — the publisher-set verb tag.
+ *   - `event_id` (text) — publisher-assigned identifier (ULIDs
+ *     recommended). Receivers use this to dedup; we keep it as text
+ *     rather than reusing `id` so a publish from one node carries an
+ *     identifier other nodes can quote in their fan-out without
+ *     coordinating SERIAL values.
+ *   - `data` (jsonb) — JSON-serialised payload.
+ *   - `created_at` (timestamptz, default now()) — used by the retention
+ *     sweep to drop old events; not exposed to subscribers.
+ *
+ * `Archetype.Event` — matches the table's append-only semantics.
+ * Non-tenanted by default (framework policy: multitenancy is opt-in).
+ * Per-tenant pub/sub is achievable by namespacing channels with the
+ * tenant ID (`tenant:42:orders.*`) — RLS on this table would force a
+ * subscriber connection to know every tenant in advance, which
+ * defeats the polling model.
+ */
+
+import { Archetype, defineSchema } from '@strav/database'
+
+export const broadcastEventSchema = defineSchema('strav_broadcast_events', Archetype.Event, (t) => {
+  t.bigSerial('id')
+  t.text('channel')
+  t.text('event_name')
+  t.text('event_id')
+  t.json<unknown>('data')
+  t.timestamp('created_at')
+})

package/src/drivers/postgres/index.ts

@@ -0,0 +1,14 @@
+export {
+  type ApplyBroadcastMigrationOptions,
+  applyBroadcastMigration,
+} from './apply_broadcast_migration.ts'
+export { broadcastEventSchema } from './broadcast_event_schema.ts'
+export {
+  type PostgresBroadcastConfig,
+  PostgresBroadcastProvider,
+} from './postgres_broadcast_provider.ts'
+export {
+  PostgresBroadcaster,
+  type PostgresBroadcasterDatabase,
+  type PostgresBroadcasterOptions,
+} from './postgres_broadcaster.ts'

package/src/drivers/postgres/postgres_broadcast_provider.ts

@@ -0,0 +1,56 @@
+/**
+ * `PostgresBroadcastProvider` — wires `PostgresBroadcaster` under the
+ * `Broadcaster` token. Apps register this INSTEAD OF
+ * `BroadcastProvider` to swap the dev-friendly memory backplane for
+ * the multi-node Postgres ledger.
+ *
+ * Reads `config.broadcast` for the polling / retention knobs; the
+ * `Database` binding is resolved straight from the container.
+ */
+
+import { type Application, ConfigRepository, ServiceProvider } from '@strav/kernel'
+import { Broadcaster } from '../../broadcaster.ts'
+import {
+  PostgresBroadcaster,
+  type PostgresBroadcasterDatabase,
+  type PostgresBroadcasterOptions,
+} from './postgres_broadcaster.ts'
+
+export interface PostgresBroadcastConfig extends Omit<PostgresBroadcasterOptions, 'db'> {
+  driver: 'postgres'
+}
+
+export class PostgresBroadcastProvider extends ServiceProvider {
+  override readonly name = 'broadcast'
+  override readonly dependencies = ['config', 'database']
+
+  override register(app: Application): void {
+    app.singleton(Broadcaster, (c) => {
+      // Resolve `Database` by string token to avoid a hard import dep
+      // on `@strav/database` from this package's barrel — the peer is
+      // optional and only loaded when this provider is registered.
+      const db = c.resolve<PostgresBroadcasterDatabase>('database' as never)
+      const cfg = c.resolve(ConfigRepository).get('broadcast') as
+        | PostgresBroadcastConfig
+        | undefined
+      return new PostgresBroadcaster({
+        db,
+        ...(cfg?.pollIntervalMs !== undefined ? { pollIntervalMs: cfg.pollIntervalMs } : {}),
+        ...(cfg?.retentionSeconds !== undefined ? { retentionSeconds: cfg.retentionSeconds } : {}),
+        ...(cfg?.cleanupIntervalMs !== undefined
+          ? { cleanupIntervalMs: cfg.cleanupIntervalMs }
+          : {}),
+        ...(cfg?.maxBufferSize !== undefined ? { maxBufferSize: cfg.maxBufferSize } : {}),
+        ...(cfg?.onOverflow !== undefined ? { onOverflow: cfg.onOverflow } : {}),
+      })
+    })
+  }
+
+  override async boot(app: Application): Promise<void> {
+    app.resolve(Broadcaster)
+  }
+
+  override async shutdown(app: Application): Promise<void> {
+    await app.resolve(Broadcaster).close()
+  }
+}

package/src/drivers/postgres/postgres_broadcaster.ts

@@ -0,0 +1,243 @@
+/**
+ * `PostgresBroadcaster` — multi-node broadcast backplane via a
+ * polled ledger table.
+ *
+ * Why polling and not LISTEN/NOTIFY:
+ *
+ *   Bun's built-in Postgres driver does not surface LISTEN/NOTIFY
+ *   to user code (as of Bun 1.3). The next-cheapest cross-node
+ *   primitive is a write-then-read ledger — same pattern as
+ *   `@strav/queue`'s `DatabaseQueue`. The polling interval
+ *   determines latency; 250ms (default) keeps round-trip on the
+ *   order of a network hop while consuming negligible DB CPU.
+ *
+ * How it works:
+ *
+ *   - `publish(channel, event)` INSERTs one row into
+ *     `strav_broadcast_events`.
+ *   - One poller per process runs `SELECT * FROM ... WHERE id > $lastId
+ *     ORDER BY id` every `pollIntervalMs`. New rows are fanned out to
+ *     local subscribers via an internal `MemoryBroadcaster`.
+ *   - The poller starts on first `subscribe()` and stops when the
+ *     broadcaster closes. Subscriber count drops to zero → poller stops
+ *     (lazy) so apps that only publish don't spin a poll loop.
+ *   - On startup, `lastId = SELECT max(id)`. Subscribers always start
+ *     from "events published from now on" — no historical replay.
+ *   - A retention sweep runs every `cleanupIntervalMs` and deletes
+ *     rows older than `retentionSeconds`. Keeps the table from growing
+ *     forever without inventing TTL semantics in app code.
+ *
+ * Apps wire `PostgresBroadcastProvider` instead of `BroadcastProvider`
+ * to use this driver; the SSE handler / Notification driver inject the
+ * shared `Broadcaster` token and see this concrete instance.
+ */
+
+import { BroadcastPublishError } from '../../broadcast_error.ts'
+import { Broadcaster } from '../../broadcaster.ts'
+import type { BroadcastEvent, BroadcastSubscription } from '../../types.ts'
+import { MemoryBroadcaster } from '../memory/memory_broadcaster.ts'
+import { broadcastEventSchema } from './broadcast_event_schema.ts'
+
+/**
+ * Minimal slice of `@strav/database`'s `DatabaseExecutor` we actually
+ * need. Declared inline (not imported) to keep the runtime peer-dep
+ * optional — apps using `MemoryBroadcaster` shouldn't pay for
+ * `@strav/database` in their bundle.
+ */
+export interface PostgresBroadcasterDatabase {
+  query<T = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<T[]>
+  execute(sql: string, params?: readonly unknown[]): Promise<number>
+}
+
+export interface PostgresBroadcasterOptions {
+  db: PostgresBroadcasterDatabase
+  /** Poll interval (ms). Default `250`. */
+  pollIntervalMs?: number
+  /**
+   * How long to retain events in the ledger before the sweep deletes
+   * them. Default `300` seconds (5 minutes). Set higher only if your
+   * SSE clients can reconnect and need replay capability; the
+   * default is "keep enough for a node to recover from a crash and
+   * catch up to live", not "audit log".
+   */
+  retentionSeconds?: number
+  /** Interval between retention sweeps. Default `30000` ms. */
+  cleanupIntervalMs?: number
+  /**
+   * Per-subscription buffer cap forwarded to the in-process
+   * `MemoryBroadcaster`. Default `1000`.
+   */
+  maxBufferSize?: number
+  /** Forwarded to the in-process `MemoryBroadcaster`'s onOverflow hook. */
+  onOverflow?: (channel: string, droppedEvent: BroadcastEvent) => void
+}
+
+interface BroadcastEventRow {
+  id: string | number
+  channel: string
+  event_name: string
+  event_id: string
+  data: unknown
+}
+
+export class PostgresBroadcaster extends Broadcaster {
+  private readonly db: PostgresBroadcasterDatabase
+  private readonly local: MemoryBroadcaster
+  private readonly tableName = broadcastEventSchema.name
+  private readonly pollIntervalMs: number
+  private readonly retentionSeconds: number
+  private readonly cleanupIntervalMs: number
+
+  private lastId = 0n
+  private cursorPrimed = false
+  private pollTimer: ReturnType<typeof setTimeout> | undefined
+  private cleanupTimer: ReturnType<typeof setInterval> | undefined
+  private closed = false
+  private pollInFlight: Promise<void> | undefined
+
+  constructor(options: PostgresBroadcasterOptions) {
+    super()
+    this.db = options.db
+    this.pollIntervalMs = options.pollIntervalMs ?? 250
+    this.retentionSeconds = options.retentionSeconds ?? 300
+    this.cleanupIntervalMs = options.cleanupIntervalMs ?? 30_000
+    this.local = new MemoryBroadcaster({
+      ...(options.maxBufferSize !== undefined ? { maxBufferSize: options.maxBufferSize } : {}),
+      ...(options.onOverflow !== undefined ? { onOverflow: options.onOverflow } : {}),
+    })
+  }
+
+  override async publish(channel: string, event: BroadcastEvent): Promise<void> {
+    let serialised: string
+    try {
+      serialised = JSON.stringify(event.data)
+    } catch (cause) {
+      throw new BroadcastPublishError('PostgresBroadcaster: event.data is not JSON-serialisable.', {
+        context: { channel, event: event.event },
+        cause,
+      })
+    }
+    try {
+      await this.db.execute(
+        `INSERT INTO "${this.tableName}" ("channel", "event_name", "event_id", "data", "created_at")
+         VALUES ($1, $2, $3, $4::jsonb, now())`,
+        [channel, event.event, event.id, serialised],
+      )
+    } catch (cause) {
+      throw new BroadcastPublishError('PostgresBroadcaster: INSERT failed.', {
+        context: { channel, event: event.event },
+        cause,
+      })
+    }
+  }
+
+  override subscribe(channel: string): BroadcastSubscription {
+    const subscription = this.local.subscribe(channel)
+    void this.ensurePoller()
+    return subscription
+  }
+
+  override async close(): Promise<void> {
+    this.closed = true
+    if (this.pollTimer !== undefined) {
+      clearTimeout(this.pollTimer)
+      this.pollTimer = undefined
+    }
+    if (this.cleanupTimer !== undefined) {
+      clearInterval(this.cleanupTimer)
+      this.cleanupTimer = undefined
+    }
+    if (this.pollInFlight !== undefined) {
+      try {
+        await this.pollInFlight
+      } catch {
+        // The next start() will surface this if it persists.
+      }
+    }
+    await this.local.close()
+  }
+
+  // ─── Internals ─────────────────────────────────────────────────────────────
+
+  /**
+   * Run one polling pass immediately and re-arm the timer. Exposed for
+   * tests so the suite doesn't have to sleep through `pollIntervalMs`.
+   */
+  async pollOnce(): Promise<void> {
+    if (this.closed) return
+    if (!this.cursorPrimed) await this.primeCursor()
+    const rows = await this.db.query<BroadcastEventRow>(
+      `SELECT "id", "channel", "event_name", "event_id", "data"
+       FROM "${this.tableName}"
+       WHERE "id" > $1
+       ORDER BY "id"
+       LIMIT 1000`,
+      [this.lastId.toString()],
+    )
+    for (const row of rows) {
+      this.lastId = BigInt(row.id)
+      await this.local.publish(row.channel, {
+        id: row.event_id,
+        event: row.event_name,
+        // Bun.SQL returns jsonb as a string (no auto-hydration on
+        // `unsafe()`). Parse here so subscribers receive the same
+        // object shape they passed to publish().
+        data: typeof row.data === 'string' ? JSON.parse(row.data) : row.data,
+      })
+    }
+  }
+
+  /** Same idea — exposed for tests that want to verify cleanup behaviour. */
+  async sweepOnce(): Promise<number> {
+    return this.db.execute(
+      `DELETE FROM "${this.tableName}" WHERE "created_at" < now() - ($1::text || ' seconds')::interval`,
+      [String(this.retentionSeconds)],
+    )
+  }
+
+  private async ensurePoller(): Promise<void> {
+    if (this.closed) return
+    if (this.pollTimer !== undefined) return
+    await this.primeCursor()
+    this.startPollLoop()
+    this.startCleanupLoop()
+  }
+
+  private async primeCursor(): Promise<void> {
+    if (this.cursorPrimed) return
+    const [row] = await this.db.query<{ max: string | number | null }>(
+      `SELECT MAX("id") AS "max" FROM "${this.tableName}"`,
+    )
+    this.lastId = row?.max !== null && row?.max !== undefined ? BigInt(row.max) : 0n
+    this.cursorPrimed = true
+  }
+
+  private startPollLoop(): void {
+    if (this.closed) return
+    const tick = async (): Promise<void> => {
+      if (this.closed) return
+      this.pollInFlight = this.pollOnce().catch(() => {
+        // Errors are silent at the loop level — we don't want a
+        // transient DB blip to tear the broadcaster down. Apps that
+        // need visibility wire the database driver's own logging.
+      })
+      await this.pollInFlight
+      this.pollInFlight = undefined
+      if (!this.closed) {
+        this.pollTimer = setTimeout(() => void tick(), this.pollIntervalMs)
+      }
+    }
+    this.pollTimer = setTimeout(() => void tick(), this.pollIntervalMs)
+  }
+
+  private startCleanupLoop(): void {
+    if (this.cleanupTimer !== undefined) return
+    this.cleanupTimer = setInterval(() => {
+      void this.sweepOnce().catch(() => {
+        // Same rationale as the poll loop.
+      })
+    }, this.cleanupIntervalMs)
+    // Allow the process to exit if this is the only timer keeping it alive.
+    this.cleanupTimer.unref?.()
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+// Public API of @strav/broadcast.
+//
+// Root barrel exports the primitive — `Broadcaster` abstract class +
+// types + errors + the in-memory provider. Drivers ship under subpaths:
+//   - `@strav/broadcast/memory`   (re-exports for explicit construction)
+//   - `@strav/broadcast/postgres` (Postgres polling-ledger backplane)
+
+export {
+  BroadcastConfigError,
+  BroadcastError,
+  BroadcastPublishError,
+  BroadcastUnauthorizedError,
+} from './broadcast_error.ts'
+export {
+  BroadcastProvider,
+  type MemoryBroadcastConfig,
+} from './broadcast_provider.ts'
+export { Broadcaster } from './broadcaster.ts'
+export {
+  type ChannelAuthorizationResult,
+  type ChannelAuthorizer,
+  ChannelAuthorizerRegistry,
+} from './channel_authorizer.ts'
+export {
+  MemoryBroadcaster,
+  type MemoryBroadcasterOptions,
+} from './drivers/memory/memory_broadcaster.ts'
+export type { BroadcastEvent, BroadcastSubscription } from './types.ts'

package/src/types.ts

@@ -0,0 +1,38 @@
+/**
+ * Public types for `@strav/broadcast`.
+ *
+ * The wire shape of a published event is intentionally tiny — `event`
+ * (a verb tag) + `data` (JSON-serialisable payload) + `id` (assigned by
+ * the publisher so receivers can dedup / replay). Driver implementations
+ * round-trip this shape verbatim; bigger wire metadata (timestamps,
+ * sender IDs, etc.) ride on `data` rather than getting promoted to
+ * separate fields here.
+ */
+
+export interface BroadcastEvent {
+  /**
+   * Event name — a verb tag like `'invoice.paid'` or `'message.created'`.
+   * Receivers branch on this; keep it stable.
+   */
+  event: string
+  /** JSON-serialisable payload. Must round-trip through `JSON.stringify`. */
+  data: unknown
+  /**
+   * Publisher-assigned identifier. ULIDs are the recommended shape —
+   * monotonically ordered, globally unique. Receivers use this to
+   * dedup retried deliveries and to seed `Last-Event-ID` replay on
+   * SSE reconnects.
+   */
+  id: string
+}
+
+/**
+ * Callback / async iterator interaction is wrapped by the
+ * `Broadcaster.subscribe()` return value. Subscribers consume events
+ * via `for await (const event of subscription) { ... }` and call
+ * `subscription.return()` (or break out of the loop) to unsubscribe.
+ */
+export interface BroadcastSubscription extends AsyncIterableIterator<BroadcastEvent> {
+  /** Unsubscribe + release driver resources. Idempotent. */
+  unsubscribe(): Promise<void>
+}