Palver

The live-channel primitive. Palver turns the same audit event outbox every other primitive emits into authenticated WebSocket pushes to browser and native runtime sessions — with no new event infrastructure, no new auth model, and the same DTO shapes the REST endpoints return.

Status: Design only. The outbox subscriber pattern is locked; the WebSocket runtime (Centrifugo, Mercure, or owned Node/Bun process) is an open choice handled in a downstream slice. This spec describes the locked contract.

What it owns

Palver owns one job: deliver audit-event-shaped pushes to authenticated client sessions, scoped to channels the client is entitled to subscribe to. It is one more subscriber on the same CompositeEventPublisher that Daneel, Speaker, Hober, and Mallow already plug into.

Palver explicitly does not own durability (the outbox is source of truth), authorization (defers to Terminus), or one-shot outbound messaging (that is Speaker; same outbox feeds both, different delivery shape).

Concepts

Channel namespace: Three shapes: entity-scoped (seldon.booking.bk_xyz), tenant-wide (tenant:t_123), sub-tenant-wide (subtenant:t_123:st_456). Entity-scoped channels do NOT carry tenantId in the name; tenancy is implicit from the JWT handshake, and the subscribe-time entitlement check binds (channel, tenant).
Event envelope: One envelope per fan-out: eventClass, entityType, entityId, occurredAt, payloadAfter, payloadBefore, channel, auditEventId. The payloadAfter shape is the same DTO GET /<primitive>/v1/<entity>/{id} returns — discrepancies are publisher bugs, not subscriber concerns.
Subscription auth: JWT in the WebSocket Upgrade headers. Same key, same claim shape as the REST endpoints. Per-channel entitlement is checked via TerminusDirectory.checkEntitlement at subscribe time — the same call Seldon Booking makes at quote time, the same call Speaker makes before dispatch.
Resume contract: Every push carries auditEventId. On reconnect the client sends the last-received id as lastEventId; Palver replays strictly-after events the client is still entitled to, bounded by outbox retention. Past the window, a gap notification tells the client to re-fetch via REST.
PalverChannelDeriver: Per-primitive service that turns an AuditEvent into the channel list it should fan out to. Tagged service; one per primitive that wants live push (Seldon for booking and scheme channels, Hober for order channels, Mallow for invoice channels). Composes via PalverFanOutPublisher.
Runtime split: Symfony PHP-FPM does not hold persistent connections. The Palver runtime runs out of process; the PHP side hands events to it over the chosen runtime's transport (Centrifugo HTTP push, Mercure publish, owned-WS internal RPC). Runtime choice is deliberately deferred — the contract above is the same either way.

API surface

Palver is consumed over WebSocket, not REST. The surface below is the wire protocol exchanged on a connected socket.

Direction	Op	Purpose
Client → Server	`HTTP Upgrade` + `Authorization: Bearer <jwt>`	Handshake. JWT verified; on failure, close 4001.
Client → Server	`{ op: "subscribe", channels: [...], lastEventId? }`	Subscribe to channels with optional resume cursor.
Server → Client	`{ op: "subscribed", channels: [...], deniedChannels: [...] }`	Per-channel entitlement result.
Server → Client	`{ eventClass, entityType, entityId, payloadAfter, ..., auditEventId }`	An event push on a subscribed channel.
Client → Server	`{ op: "ping" }`	Heartbeat (every 30s).
Server → Client	`{ op: "pong" }`	Heartbeat response.
Server → Client	`{ op: "gap", channel, lastDelivered }`	Replay window exceeded; client should re-fetch via REST.
Server → Client	Close 4001 / 4003 / 4008 / 4010	Auth failed / forbidden / policy / server going away.

Example: subscribe to a booking

After the WebSocket Upgrade with a JWT, the client subscribes:

// client → server
{
  "op": "subscribe",
  "channels": [
    "seldon.booking.bk_01JAZB…",
    "tenant:t_01J8K2…"
  ],
  "lastEventId": "ae_01JAZD…"
}

// server → client
{ "op": "subscribed",
  "channels":      ["seldon.booking.bk_01JAZB…", "tenant:t_01J8K2…"],
  "deniedChannels": [] }

// server → client (push on booking.confirmed)
{
  "eventClass":   "seldon_booking.confirmed",
  "entityType":   "seldon_booking",
  "entityId":     "bk_01JAZB…",
  "occurredAt":   "2026-06-10T14:31:22Z",
  "channel":      "seldon.booking.bk_01JAZB…",
  "auditEventId": "ae_01JAZE…",
  "payloadAfter": { /* same shape as GET /seldon/v1/bookings/bk_01JAZB… */ }
}

How it fits with the rest

flowchart LR
  OB[(Audit outbox)] --> Pv(Palver)
  Pv -- checkEntitlement --> Te[Terminus]
  Pv --> WS[WebSocket sessions]
  Pv -. shares outbox with .-> Sp[Speaker]
  Pv -. shares outbox with .-> D[Daneel]

Palver subscribes to the same outbox every other event consumer subscribes to. A single booking.confirmed event can fan to Speaker (which sends the confirmation email under consent gate), to Daneel (which starts the reminder workflow), and to Palver (which pushes the new row to an operator's live booking list). All three see the same envelope; each delivers it in its own shape. Terminus is the authorization layer for subscriptions, same as for every other access decision on the platform.