---
name: kv-or-stream
description: Decide between KV Watch and JetStream Stream for a new communication path. Use when designing inter-component communication, adding new message flows, or choosing storage primitives.
argument-hint: [description of the communication being designed]
---

# KV Watch vs JetStream Stream Decision

## What are you designing?

$ARGUMENTS

## The 4-Test Heuristic

Apply these tests in order. The first clear answer is usually sufficient.

### Test 1: Restart Test (sharpest)

If this processor restarted, should it re-process messages it already handled?

- **Yes** (re-process is correct recovery) --> **KV Watch**
- **No** (re-process would be wrong) --> **JetStream Stream**

### Test 2: Fan-out vs Queue

Should multiple processors all react to this, or should only one handle it?

- **All react** (fan-out) --> **KV Watch**
- **Only one handles it** (queue) --> **JetStream Stream**

### Test 3: Processing Time

Is the processing fast and idempotent, or slow with real side effects?

- **Fast and idempotent** --> **KV Watch**
- **Slow or has side effects** --> **JetStream Stream**

### Test 4: Nature Test

Is this a fact about the world, or a request to do something?

- **Fact** (entity state, index entry, current status) --> **KV Watch**
- **Request** (execute task, call LLM, run tool) --> **JetStream Stream**

## Conflict Check

If any test gives conflicting answers, the concept may be two things conflated. Revisit whether it should be split into separate concerns.

## Common Cases Reference

| Communication | Primitive | Reason |
|--------------|-----------|--------|
| Entity state changed | KV Watch | Fact; fan-out; fast; idempotent |
| New task to execute | JetStream Stream | Request; queue; expensive; side effects |
| Index update | KV Write (others watch) | Fact; fan-out; fast |
| LLM call | JetStream Stream | Request; queue; slow; costly |
| Loop current state | KV | Fact; queryable; recoverable |
| Tool execution request | JetStream Stream | Request; queue; side effects |
| Tool result returned | JetStream Stream | Response; once; push delivery |
| Workflow trigger | JetStream Stream | Request; queue; expensive |
| Workflow execution state | KV | Fact; queryable; recoverable |
| Sensor telemetry | KV Write | Fact; latest-value semantics |

## Key Architecture Context

**The KV Twofer**: Every NATS KV bucket is backed by a JetStream stream. A single KV write gives you three interfaces simultaneously:
- **State**: `kv.Get(key)` returns current value
- **Events**: `kv.Watch(pattern)` fires on every change (fan-out)
- **History**: Replay from any revision for audit trail

**Bootstrap phase**: When a KV watcher starts, it delivers ALL current values matching the pattern, then a `nil` entry signals transition to live updates. Processors must distinguish bootstrap from live to avoid treating existing entities as "new" events on restart.

**JetStream consumers**: With `DeliverPolicy: "new"` on a durable consumer, restart resumes from last ack. No replay of already-handled messages.

**Using both is normal**: A component using KV for state AND JetStream for work items in the same process is the standard pattern (see agentic-loop).

Read `docs/concepts/03-streams-vs-kv-watches.md` for full documentation.
Read `docs/concepts/02-kv-twofer.md` for KV Twofer details.