ADR-032: NATS JetStream Messaging Architecture

Status: Proposed
Version: 1.0
Date: 2025-12-28
Supersedes: N/A
Related ADRs: ADR-033 (Kernel-Shell), ADR-030 (VibesPro™ Foundation)
Related PRDs: PRD-022

Context

SEA™ and VibesPro™ are separate bounded contexts with:

Conceptual ownership: Each owns its domain concepts
Data ownership: Each owns its database (same server, separate DBs)

These contexts need reliable communication for:

Event-driven state synchronization
Async command processing
Failure isolation and recovery

The transcript evaluated multiple options:

DB-to-DB relay (no broker)
Kafka/RabbitMQ/SQS
NATS JetStream

Decision

We adopt NATS JetStream with the following architecture:

Per-Context Streams

Stream	Owner	Subjects	Purpose
`SEA_EVENTS`	SEA™	`sea.event.>`	Events emitted by SEA™
`VIBESPRO_EVENTS`	VibesPro™	`vibespro.event.>`	Events emitted by VibesPro™

Subject Convention

{context}.event.{snake_case_name}.v{n}

Examples:

vibespro.event.vibe_created.v1
vibespro.event.vibe_scored.v1
sea.event.governance_decision_recorded.v1

Rule: Never change meaning of .v1 once emitted. Create .v2 on breaking changes.

Outbox + Inbox Pattern

Outbox (per context DB):

CREATE TABLE outbox_events (
  id UUID PRIMARY KEY,
  aggregate_type TEXT NOT NULL,
  aggregate_id TEXT NOT NULL,
  event_type TEXT NOT NULL,
  payload JSONB NOT NULL,
  occurred_at TIMESTAMPTZ NOT NULL,
  correlation_id UUID,
  causation_id UUID,
  published_at TIMESTAMPTZ,
  publish_attempts INT DEFAULT 0,
  publish_error TEXT
);

CREATE INDEX idx_outbox_unpublished ON outbox_events (occurred_at)
  WHERE published_at IS NULL;

Inbox (per context DB):

CREATE TABLE inbox_messages (
  message_id UUID PRIMARY KEY,
  subject TEXT NOT NULL,
  received_at TIMESTAMPTZ NOT NULL,
  processed_at TIMESTAMPTZ,
  attempts INT DEFAULT 0,
  last_error TEXT
);

Pull-Based Consumers

Durable Consumer: {target_context}__from_{source_context}
Example: sea__from_vibespro

Setting	Value	Rationale
Ack Policy	Explicit	Reliable processing
Ack Wait	60-120s	Handle slow handlers
Max Deliver	10-20	DLQ after failures
Max In-Flight	10-50	Backpressure control

Publish Deduplication

Use Nats-Msg-Id header set to outbox event UUID:

JetStream deduplicates within its window
Inbox PK provides ultimate idempotency

Rationale

NATS JetStream advantages:
- At-least-once with delivery tracking
- Publisher dedupe via Nats-Msg-Id
- Pull consumers for backpressure
- Simpler ops than Kafka
Per-context streams:
- Clear ownership
- Independent retention policies
- Cleaner governance
Outbox pattern:
- Atomic writes (state + event in one TX)
- Guaranteed delivery even on publisher crash
Inbox pattern:
- Exactly-once processing semantics
- Safe under redelivery storms

Constraints

MUST

MUST write outbox event in same transaction as state change
MUST set Nats-Msg-Id header to outbox event UUID
MUST check inbox PK before processing (dedupe)
MUST mark processed_at before ACKing
MUST version all event subjects (.v1, .v2)

MUST NOT

MUST NOT publish directly without outbox
MUST NOT ACK before inbox insert succeeds
MUST NOT change .v1 payload meaning post-release
MUST NOT share streams across unrelated contexts

Isomorphic Guarantees

Spec Concept	SEA-DSL Target	Mapping
OutboxEvent	Entity node	1:1 field mapping
InboxMessage	Entity node	1:1 field mapping
JetStream stream	Infrastructure config	Per-context
Subject convention	Event contract	Schema preservation

System Invariants

INV-ID	Invariant	Type	Enforcement
INV-020	At-least-once delivery	System	JetStream redelivery
INV-021	Exactly-once processing	System	Inbox PK constraint
INV-022	State and event atomically written	Process	Same DB transaction
INV-023	Events versioned immutably	Contract	Subject naming

Quality Attributes

Attribute	Target	Rationale
Reliability	Zero lost events	Outbox guarantees
Idempotency	No duplicate processing	Inbox PK
Latency	p99 < 500ms event delivery	Pull batch efficiency
Recoverability	Full replay from stream	JetStream persistence

Bounded Contexts Impacted

SEA™ Kernel: Publishes to SEA_EVENTS, consumes VIBESPRO_EVENTS
VibesPro™: Publishes to VIBESPRO_EVENTS, consumes SEA_EVENTS
All future BCs: Same pattern

Consequences

Positive

Reliable async communication without distributed TX
Clean failure isolation per context
Stream replay for debugging/recovery
Works with in-process or separate deployment

Negative

Additional infrastructure (NATS server)
Complexity of outbox publisher workers
Must handle DLQ processing

Mitigations

NATS is lightweight vs Kafka
Standardized Rust worker template
DLQ alert integration

ACK Rules (Critical)

When Rust consumer pulls a message:

Extract message_id from Nats-Msg-Id header
INSERT INTO inbox_messages ... ON CONFLICT DO NOTHING
If conflict → ACK immediately (already processed)
Call handler (FastAPI /handle)
Response handling:
- 200 OK → mark processed → ACK
- 409 Conflict → mark processed → ACK
- 422 Unprocessable → route to DLQ → ACK
- 5xx / timeout → DON’T ACK (let redeliver)