# Senior NATS JetStream playbook

Compressed reference for the senior-only NATS extension. Pair with [cheat-sheet.md](./cheat-sheet.md), [GLOSSARY.md](./GLOSSARY.md), and [repo-nats-map.md](./repo-nats-map.md).

## The senior shift
Intermediate understanding is: "I know core NATS vs JetStream, subjects and queue groups, streams and consumers, the golib wrapper, handleMsg, at-least-once delivery, the learner-owned subscribers, and NATS vs Kafka in this repo."

Senior understanding is: "I can reason about subject taxonomy, queue-group scaling and pull-vs-push choice, replay safety and stale events, poison-message and DLQ trade-offs, and whether a NATS design is making truthful claims about delivery, tenancy, and operations."

## Six senior lenses
1. **Subjects are architecture** — naming choices become routing and ownership boundaries.
2. **Queue groups are not the whole scaling story** — handler speed and backpressure still matter.
3. **Replay is useful but not free** — stale-event and idempotency boundaries decide whether recovery stays safe.
4. **Dedup is only one layer** — publish dedup does not replace application idempotency.
5. **DLQ is about liveness plus evidence** — not just “store failed messages somewhere.”
6. **Review is about guarantee truthfulness** — ask what the design really guarantees and what it trades away.

## Senior review checklist
- Can you explain why this subject family and wildcard boundary are the right shape?
- Can you justify push queue-group versus pull for the actual workload?
- Can you distinguish publish dedup from replay-safe application behavior?
- Can you explain how stale-event handling and SkipMsgOlderThan fit into correctness?
- Can you describe the real trade-off in Ack-only failure handling and no-DLQ design?
- Can you verify that tenancy and tracing survive the async hop safely through the envelope path?
- Can you explain when NATS remains the right bus and when Kafka is the better fit?

## Interview answer shapes
### Why isn’t subject taxonomy just naming style?
Because subject families determine wildcard capture, stream ownership, ACL boundaries, and what events get replayed or reasoned about together.

### Why don’t queue groups solve every scaling problem?
Because throughput still depends on handler cost, in-flight pressure, and whether push or pull matches the workload shape.

### Why isn’t Nats-Msg-Id dedup enough by itself?
Because it only suppresses some repeated publishes within the dedup window; consumer redelivery and stale-event semantics still require application idempotency.

### What is the real point of a DLQ here?
To preserve the failed event and its context while letting the main flow keep progressing safely.

### What is the real job of a senior NATS reviewer?
To ask what exact guarantees the design provides about delivery, replay, tenancy, and failure handling, and whether the trade-offs match the implementation.