Subject Naming¶

All message subjects follow a consistent hierarchy. The subject scheme is transport-agnostic; any system that supports hierarchical topic naming and wildcard subscriptions can implement it.

Subject Map¶

NATS Subjects¶

Subject	Purpose
`mesh.agent.{name}`	Invocation (queue group subscription)
`mesh.agent.{name}.events`	Pub/sub event emissions from publisher agents
`mesh.stream.{request_id}`	Streaming response chunks
`mesh.errors.{name}`	Dead-letter subject for handler errors
`mesh.results.{request_id}`	Async callback reply subject
`mesh.death.{name}`	Death notices when an agent leaves the mesh
`mesh.logs.{name}`	Structured log events (level-gated, ephemeral)
`mesh.health.{name}`	Reserved for the heartbeat layer deferred by ADR-0016 v1 — no producer yet; the observer role is already granted subscribe access for forward compatibility

{name} is the agent's dotted identifier (ADR-0049). Names with dots embed the channel hierarchy directly (nlp.summarizer, finance.risk.scorer); root-level agents have no dots (echo).

KV Keys (not NATS subjects)¶

Bucket	Key	Purpose
`mesh-catalog`	`catalog`	Lightweight catalog index (JSON array)
`mesh-registry`	`{name}`	Full agent contract
`mesh-context`	Agent-defined	Shared state between agents
`mesh-instances`	`{instance_id}`	Host liveness correlation (agents served)
`mesh-observability`	`global` / `{name}`	Log-level config (per-agent wins)

Object Store Buckets¶

Bucket	Purpose
`mesh-artifacts`	Binary artifact storage (`mesh.workspace`) — files, images, embeddings, anything that doesn't fit a KV string (shared state)

Wildcards¶

The subject hierarchy enables wildcard subscriptions:

mesh.agent.finance.*      # All agents one level deep under finance
mesh.agent.finance.>      # All agents in finance and sub-channels
mesh.errors.>             # All dead-letter errors
mesh.death.>              # All death notices
mesh.logs.>               # All log events (mesh.logs.nlp.> for one channel)

Channel Mapping¶

Channels are the leading dot-segments of a name. They map directly to subject segments:

Name	Channel	Invocation Subject
`echo`	(root)	`mesh.agent.echo`
`nlp.summarizer`	`nlp`	`mesh.agent.nlp.summarizer`
`finance.risk.scorer`	`finance.risk`	`mesh.agent.finance.risk.scorer`