NATS service patterns

Every ORE Studio service is a set of subjects it answers and messages it sends. NATS is the substrate and ores.nats is the wrapper, but neither says how a service must use them. This hub is the answer: the patterns that govern writing NATS code in this codebase, what each one requires, why it is required, and what breaks without it.

A pattern here is a rule about a call site, not a general architectural idea. It states the shape of the code — which `ores.nats` call, with which arguments, in which place — and the guarantee that shape buys. The rule is a contract: a service that does not follow it is wrong, even when it compiles and appears to work, because the failure it invites is silent and arrives later.

Three rules govern the language:

• One call site, one pattern. A pattern answers one question about one interface, and its page names the exact call that must appear.
• Every pattern states its rationale and its failure. A rule with no named failure is a style preference, and does not belong here. Each page's * Failure handling and * Pitfalls say what goes wrong without it.
• The pattern owns the mechanism; the architecture page owns the design. A pattern page states the call and the guarantee. The page that designs a service links the pattern and states only its own choices.

The hub covers how a service speaks on the bus. It does not cover what it says: the subject grammar, the verbs, the envelopes and the error model on the wire belong to the NATS entity protocol specification, and the encoded payload belongs to the NATS Wire Format; both are ordered by Message Queue, not here. It does not cover who a caller is or how a token travels; that is Identity and Access.

Read the groups in order. A later group assumes the guarantees the earlier groups establish: a publish is only as durable as the subscription that reads it, and an error is only reportable once the message carrying it is acknowledged.

Start from the question, not the call. Find the group whose question your code faces, then read its pages. Each page's * Context says when the pattern applies and * Related patterns names the alternatives. When no pattern fits, write the code without one and record the gap on the story. Do not stretch a pattern to fit.

To add a pattern, run compass add nats_pattern --pattern-group <group>, fill in every section, name the ores.nats call it governs, and add it to its group above. See How do I create a new doc?.

Message Queue owns the structure of the messaging cluster: the bus, the namespace, the message contract and the binding. This hub is the rulebook for the binding half of it.

Service architecture patterns owns the vocabulary two services share: Request-Reply, Competing Consumers, Retry, Idempotent Receiver, Log Aggregation. Each page here names the pattern there it specialises and states only the mechanism this codebase requires. The division of responsibility between the two hubs is stated under * Scope above.

Anatomy of a Service owns how a service is assembled: its components, its registry entry, its certificates, its accounts. This hub owns how the assembled service speaks.

• ores.nats — the library every pattern here is stated in terms of.
• NATS — the substrate: subjects, pub/sub, request/reply, queue groups, JetStream.
• JetStream streams and durable consumers — the streams this deployment creates and what a subject rename strands.
• Service Bootstrap Phases — when a subject becomes callable, and why that order matters.
• Knowledge — the index this structure note hangs from.
• Zettelkasten — what a structure note is, and why its order is authored rather than computed.
• NATS documentation, Delivery and acknowledgment — the ack/redeliver loop the subscription group rests on.
• NATS documentation, Request-Reply Resilience — the two request failures and how to retry them.
• NATS documentation, Drain & Shutdown — close against drain, and why drain belongs last.