NATS Transport Binding

The NATS binding maps AGH Network envelopes onto NATS subjects. It preserves the core semantics defined by envelopes, message kinds, and delivery guarantees.

This page is normative unless a section is marked as an example.

Binding scope

The baseline binding uses NATS Core subjects and JSON envelope payloads.

Peers MUST include the stable workspace ID in every subject. Channel-only subjects are obsolete and MUST NOT be accepted by v0 peers.

Subject grammar

Subjects use this hierarchy:

agh.network.v0.<workspace_id>.<channel>.broadcast
agh.network.v0.<workspace_id>.<channel>.peer.<route_token>

Route tokens

Each NATS peer MUST derive a route token for direct subjects.

For a verified sender:

from: patch-worker@56475aa75463474c0285df5dbf2bcab7
route token: 56475aa75463474c0285df5dbf2bcab7
direct subject: agh.network.v0.ws_alpha.builders.peer.56475aa75463474c0285df5dbf2bcab7

For an unverified v0-style peer:

peer_id: reviewer.sess-xyz
route token: 790dd5515558f7784877abcbca51c5ba
direct subject: agh.network.v0.ws_alpha.builders.peer.790dd5515558f7784877abcbca51c5ba

The to field in a directed envelope MUST still contain the target peer identity, not the route token. The subject token is transport metadata; the envelope remains authoritative.

Subject mapping

The NATS binding uses two transport-level subjects per channel. Note that "direct subject" here means a NATS subject targeted at one peer; it is distinct from the AGH Network conversation surface surface:"direct" (a restricted two-party room). A surface:"thread" envelope addressed to one peer also publishes to a peer direct NATS subject.

Sending rules:

• A sender MUST publish broadcast envelopes to the channel broadcast subject.
• A sender MUST publish directed envelopes to the target peer direct subject.
• A sender SHOULD broadcast greet.
• A sender SHOULD use direct subjects for targeted whois, conversation-bearing kinds with to, receipt, and trace.
• A sender MUST preserve the envelope to, surface, and matching container ID when publishing to a direct subject.

Joining a channel

A NATS Peer joins a channel by subscribing to the required subjects and announcing presence:

1. Subscribe to agh.network.v0.<workspace_id>.<channel>.broadcast.
2. Subscribe to agh.network.v0.<workspace_id>.<channel>.peer.<own_route_token>.
3. SHOULD publish a greet envelope to the broadcast subject.
4. SHOULD publish greet again after reconnecting.

Periodic greet acts as a presence heartbeat. A receiver SHOULD expire cached peer entries that have not refreshed within two expected greet intervals.

Connection configuration

The protocol binding does not standardize a configuration file format. A NATS Peer needs these effective settings:

The current AGH Runtime local configuration uses these fields:

[network]
enabled = true
default_channel = "default"
port = -1
max_payload = 1048576
greet_interval = 30
max_replay_age = 300
max_queue_depth = 100

NATS delivery semantics

The NATS binding inherits the core protocol delivery posture:

NATS publish success means the broker accepted the payload. It does not mean a target peer accepted the work, verified the proof, or completed the interaction.

Request-reply

Implementations MAY use NATS request-reply mechanics for local convenience. Core protocol correlation remains authoritative.

If NATS request-reply is used:

• The envelope still MUST include reply_to when it is replying to another envelope.
• Conversation-bearing messages still MUST include surface plus the matching thread_id or direct_id and, when the message kind requires it, work_id.
• trace_id and causation_id MUST remain inside the envelope when used.
• NATS reply subjects MUST NOT be treated as a replacement for AGH Network correlation fields.

JetStream persistence profile

JetStream is optional. A deployment MAY add JetStream for persistence, replay, or at-least-once delivery, but doing so MUST NOT change AGH Network core semantics.

Recommended stream shape:

stream name: AGH_NETWORK_V0
subjects: agh.network.v0.>
retention: limits or workqueue, according to deployment policy
max message size: at least 1048576 bytes
discard policy: deployment-defined

JetStream-specific requirements:

• A JetStream publish acknowledgement means the broker persisted the envelope; it does not mean the receiver accepted the work.
• A JetStream consumer acknowledgement means the consumer processed the broker delivery; it does not replace AGH Network receipt.
• Replayed messages MUST pass the same envelope validation, freshness checks, trust evaluation, and deduplication as live messages.
• Redelivery MUST preserve the original envelope id.
• Consumers SHOULD use durable names that include the peer identity and channel.
• Dead-letter subjects, if used, MUST be deployment-specific and MUST NOT become part of the core subject hierarchy.

Version interop

AGH Runtime v0 is a hard cut from channel-only subjects. A v0 peer subscribes to exactly the workspace-qualified broadcast subject and its own workspace-qualified peer subject for every (workspace_id, channel) membership. Bridges from older channel-only experiments must republish as new v0 senders after validating the workspace boundary; they MUST NOT forward channel-only subjects directly into a v0 runtime.

Security notes

Transport security and message verification solve different problems.

• NATS TLS or credentials authenticate a connection to the broker.
• The Ed25519 trust profile verifies the envelope and sender handle.
• Neither one by itself grants application authorization.

Receivers that opt into the v1 trust profile MUST verify proofs according to signature verification before treating an envelope as verified, even if the message arrived over authenticated NATS.