docs(acp-nats): document subject-to-transport mapping in subjects.rs

Signed-off-by: Yordis Prieto <yordis.prieto@gmail.com>

Author: yordis

rsworkspace/crates/acp-nats/src/nats/subjects.rs

@@ -1,20 +1,92 @@
+//! # ACP NATS Subject Hierarchy
+//!
+//! Every ACP subject, its transport, and why.
+//!
+//! ## Core NATS (request/reply or fire-and-forget)
+//!
+//! Stateless operations where the agent must be online now and the response
+//! is immediate. No session state to recover on failure — just retry.
+//!
+//! | Subject                              | Pattern          | Rationale                                    |
+//! |--------------------------------------|------------------|----------------------------------------------|
+//! | `agent.initialize`                   | request/reply    | Handshake, agent must be alive               |
+//! | `agent.authenticate`                 | request/reply    | Auth, agent must be alive                    |
+//! | `agent.session.list`                 | request/reply    | Read-only query, no state change             |
+//! | `agent.ext.>`                        | request/reply    | Stateless global extension calls             |
+//! | `session.{id}.client.*`              | request/reply    | Agent-to-bridge ops (fs, terminal, perms)    |
+//!
+//! ## JetStream (durable delivery via streams)
+//!
+//! Commands that create or mutate session state. Durable delivery means the
+//! agent receives the command even after a restart, and the bridge can replay
+//! responses on reconnect.
+//!
+//! | Subject                                      | Stream          | Rationale                                  |
+//! |----------------------------------------------|-----------------|--------------------------------------------|
+//! | `agent.session.new`                           | GLOBAL          | Creates session state                      |
+//! | `session.*.agent.cancel`                      | COMMANDS        | Must survive agent reconnect               |
+//! | `session.*.agent.prompt`                      | COMMANDS        | Long-running, must survive restarts        |
+//! | `session.*.agent.load`                        | COMMANDS        | Loads session into agent, mutates state    |
+//! | `session.*.agent.close`                       | COMMANDS        | Ends session lifecycle                     |
+//! | `session.*.agent.set_mode`                    | COMMANDS        | Mutates session config                     |
+//! | `session.*.agent.set_config_option`           | COMMANDS        | Mutates session config                     |
+//! | `session.*.agent.set_model`                   | COMMANDS        | Mutates session config                     |
+//! | `session.*.agent.fork`                        | COMMANDS        | Creates new session from existing          |
+//! | `session.*.agent.resume`                      | COMMANDS        | Resumes session, mutates state             |
+//! | `session.*.agent.prompt.response.>`           | RESPONSES       | Streamed prompt responses                  |
+//! | `session.*.agent.response.>`                  | RESPONSES       | One-shot command responses                 |
+//! | `session.*.agent.ext.ready`                   | RESPONSES       | Extension ready signal                     |
+//! | `session.*.agent.cancelled`                   | RESPONSES       | Cancellation confirmation                  |
+//! | `session.*.agent.update.>`                    | NOTIFICATIONS   | Async streaming updates                    |
+//!
+//! ## JetStream Streams on Core NATS Subjects
+//!
+//! The Core NATS subjects above also have JetStream streams configured on
+//! them. NATS is pub/sub — when a message is published, every subscriber
+//! gets a copy, and a JetStream stream is just another subscriber. The
+//! stream persists a copy of every message that matches its subject filter.
+//!
+//! The bridge doesn't use these streams for the request/reply flow — it
+//! uses Core NATS directly. But the streams are there, capturing every
+//! message for observability: audit logs, metrics, debugging replay,
+//! alerting. Create consumers on these streams after the fact to read them.
+//!
+//! | Subject                 | Stream     |
+//! |-------------------------|------------|
+//! | `agent.initialize`      | GLOBAL     |
+//! | `agent.authenticate`    | GLOBAL     |
+//! | `agent.session.new`     | GLOBAL     |
+//! | `agent.ext.>`           | GLOBAL_EXT |
+//!
+//! ## Not in JetStream
+//!
+//! | Subject                | Reason                                                    |
+//! |------------------------|-----------------------------------------------------------|
+//! | `agent.session.list`   | Pure read, no state change, no audit value                |
+//! | `session.*.client.>`   | Agent-to-bridge ops, bridge IS the process, no disconnect |
+
 pub mod agent {
+    /// Bridge: Core NATS request/reply. Stream: GLOBAL (observability).
     pub fn initialize(prefix: &str) -> String {
         format!("{}.agent.initialize", prefix)
     }
 
+    /// Bridge: Core NATS request/reply. Stream: GLOBAL (observability).
     pub fn authenticate(prefix: &str) -> String {
         format!("{}.agent.authenticate", prefix)
     }
 
+    /// Bridge: JetStream publish. Stream: GLOBAL.
     pub fn session_new(prefix: &str) -> String {
         format!("{}.agent.session.new", prefix)
     }
 
+    /// Bridge: Core NATS request/reply. No stream.
     pub fn session_list(prefix: &str) -> String {
         format!("{}.agent.session.list", prefix)
     }
 
+    /// Bridge: Core NATS request/reply. Stream: GLOBAL_EXT (observability).
     pub fn ext(prefix: &str, method: &str) -> String {
         format!("{}.agent.ext.{}", prefix, method)
     }
@@ -28,10 +100,12 @@ pub mod agent {
 
 pub mod session {
     pub mod agent {
+        /// Bridge: JetStream publish. Stream: COMMANDS.
         pub fn load(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.agent.load", prefix, session_id)
         }
 
+        /// Bridge: JetStream publish. Stream: COMMANDS.
         pub fn prompt(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.agent.prompt", prefix, session_id)
         }
@@ -40,53 +114,69 @@ pub mod session {
             format!("{}.session.*.agent.prompt", prefix)
         }
 
+        /// Bridge: Core NATS publish (fire-and-forget). Stream: COMMANDS.
+        ///
+        /// Published via `PublishClient`, not `JetStreamPublisher`. The COMMANDS
+        /// stream captures it because the stream subscribes to this subject.
+        /// The agent-side consumes it from the stream.
         pub fn cancel(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.agent.cancel", prefix, session_id)
         }
 
+        /// Agent → bridge broadcast confirming cancellation. Stream: RESPONSES.
         pub fn cancelled(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.agent.cancelled", prefix, session_id)
         }
 
+        /// Bridge: JetStream publish. Stream: COMMANDS.
         pub fn set_mode(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.agent.set_mode", prefix, session_id)
         }
 
+        /// Bridge: JetStream publish. Stream: COMMANDS.
         pub fn set_config_option(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.agent.set_config_option", prefix, session_id)
         }
 
+        /// Bridge: JetStream publish. Stream: COMMANDS.
         pub fn set_model(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.agent.set_model", prefix, session_id)
         }
 
+        /// Bridge: JetStream publish. Stream: COMMANDS.
         pub fn fork(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.agent.fork", prefix, session_id)
         }
 
+        /// Bridge: JetStream publish. Stream: COMMANDS.
         pub fn resume(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.agent.resume", prefix, session_id)
         }
 
+        /// Bridge: JetStream publish. Stream: COMMANDS.
         pub fn close(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.agent.close", prefix, session_id)
         }
 
+        /// Agent → bridge signal. Stream: RESPONSES.
         pub fn ext_ready(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.agent.ext.ready", prefix, session_id)
         }
 
+        /// Agent → bridge async notification. Stream: NOTIFICATIONS.
         pub fn update(prefix: &str, session_id: &str, req_id: &str) -> String {
             format!("{}.session.{}.agent.update.{}", prefix, session_id, req_id)
         }
 
+        /// Agent → bridge streamed response. Stream: RESPONSES.
         pub fn prompt_response(prefix: &str, session_id: &str, req_id: &str) -> String {
             format!(
                 "{}.session.{}.agent.prompt.response.{}",
                 prefix, session_id, req_id
             )
         }
 
+        /// Agent → bridge one-shot response. Stream: RESPONSES.
         pub fn response(prefix: &str, session_id: &str, req_id: &str) -> String {
             format!(
                 "{}.session.{}.agent.response.{}",
@@ -96,44 +186,53 @@ pub mod session {
     }
 
     pub mod client {
+        /// Agent → bridge. Core NATS request/reply. Stream: CLIENT_OPS.
         pub fn fs_read_text_file(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.client.fs.read_text_file", prefix, session_id)
         }
 
+        /// Agent → bridge. Core NATS request/reply. Stream: CLIENT_OPS.
         pub fn fs_write_text_file(prefix: &str, session_id: &str) -> String {
             format!(
                 "{}.session.{}.client.fs.write_text_file",
                 prefix, session_id
             )
         }
 
+        /// Agent → bridge. Core NATS request/reply. Stream: CLIENT_OPS.
         pub fn session_request_permission(prefix: &str, session_id: &str) -> String {
             format!(
                 "{}.session.{}.client.session.request_permission",
                 prefix, session_id
             )
         }
 
+        /// Agent → bridge. Core NATS request/reply. Stream: CLIENT_OPS.
         pub fn session_update(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.client.session.update", prefix, session_id)
         }
 
+        /// Agent → bridge. Core NATS request/reply. Stream: CLIENT_OPS.
         pub fn terminal_create(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.client.terminal.create", prefix, session_id)
         }
 
+        /// Agent → bridge. Core NATS request/reply. Stream: CLIENT_OPS.
         pub fn terminal_kill(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.client.terminal.kill", prefix, session_id)
         }
 
+        /// Agent → bridge. Core NATS request/reply. Stream: CLIENT_OPS.
         pub fn terminal_output(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.client.terminal.output", prefix, session_id)
         }
 
+        /// Agent → bridge. Core NATS request/reply. Stream: CLIENT_OPS.
         pub fn terminal_release(prefix: &str, session_id: &str) -> String {
             format!("{}.session.{}.client.terminal.release", prefix, session_id)
         }
 
+        /// Agent → bridge. Core NATS request/reply. Stream: CLIENT_OPS.
         pub fn terminal_wait_for_exit(prefix: &str, session_id: &str) -> String {
             format!(
                 "{}.session.{}.client.terminal.wait_for_exit",