NATS bridge

publish committed Chronacta events to NATS with durable checkpointing.

Chronacta remains the source of truth. NATS delivery is at-least-once; consumers must be idempotent.

Enable on server

Set environment variables when starting chronacta-server:

Variable	Default	Description
`CHRONACTA_NATS_URL`	(disabled)	NATS server URL, e.g. `nats://127.0.0.1:4222`
`CHRONACTA_NATS_SUBJECT_PREFIX`	`chronacta`	Subject prefix for published messages
`CHRONACTA_NATS_STREAM_FILTER`	(empty)	Optional stream id filter
`CHRONACTA_NATS_BRIDGE_ID`	`default`	Bridge id for checkpoint path
`CHRONACTA_NATS_MAX_BUFFER`	`1024`	Bounded outage counter before backpressure
`CHRONACTA_NATS_POLL_INTERVAL`	`250ms`	Catch-up poll interval
`CHRONACTA_NATS_RECONNECT_WAIT`	`1s`	Delay before retry after publish failure

Checkpoint file: data/integrations/nats/<bridge_id>/checkpoint.json

Subjects

Each committed event is published to:

{prefix}.all — global ordering by committed position
{prefix}.stream.{stream_id} — per-stream fan-out (. in stream ids replaced with _)

Message payload

JSON object:

{
  "event_id": "uuid",
  "stream_id": "orders-1",
  "stream_version": 1,
  "global_position": 42,
  "event_type": "OrderCreated",
  "data": {"order_id": "1"},
  "metadata": {},
  "schema_name": "",
  "schema_version": 0
}

Outage behavior

Bridge reads from checkpoint + 1 via $all.
On NATS publish failure: bridge pauses, records last_error, retries after CHRONACTA_NATS_RECONNECT_WAIT.
Checkpoint advances only after successful publish — no silent skip.
After NATS recovery, bridge resumes automatically; use replay if manual catch-up is needed.

CLI

./bin/chronacta integration nats status [-server ADDRESS] [-json]
./bin/chronacta integration nats replay [-from POSITION] [-json]

replay -from 0 resets checkpoint and republishes from the beginning (at-least-once to NATS).

gRPC

IntegrationService:

GetNATSBridgeStatus — permission stream.read
ReplayNATSBridge — permission backup