# Gateway

`aip-gateway` is the composition boundary between native envelopes, runtime
services, profiles, transports, and connectors. It remains a library crate so it
can be embedded by `aipd`, tests, and product-specific host processes.

## Responsibilities

- Accept native `Envelope` values.
- Negotiate handshakes and session creation.
- Return local manifests.
- Dispatch actions through `aip-runtime` handlers.
- Register outbound connectors and wire their capabilities into runtime handler routing.
- Route first-class delegation requests to configured remote peers.
- Route every native message family into lifecycle stores.
- Deliver asynchronous callbacks over native HTTP, native NATS, or in-process SSE.
- Convert runtime failures into typed AIP error envelopes.
- Preserve session and correlation metadata on responses.

`aipd` exposes the same gateway over native HTTP and, when configured, native
NATS request/reply. It also exposes MCP and A2A compatibility ingress endpoints.
Those endpoints translate profile DTOs into native envelopes before calling
`aip-gateway`; they do not duplicate capability execution or lifecycle
semantics.

When `--storage-dir` or `AIPD_STORAGE_DIR` is configured, `aipd` constructs the
gateway with file-backed runtime stores for sessions, idempotency, event log,
lifecycle state, and delegation graph state. Without that option the daemon
remains ephemeral and uses in-memory stores.

Remote delegation routes are selected by delegate principal and/or child
capability. Native HTTP routes post a `DelegationRequest` envelope to a peer
endpoint and expect a `DelegationResult` envelope in response. Native NATS routes
use request/reply on the configured subject. If no route matches, runtime falls
back to local delegate execution.

Connector registration is also centralized at the gateway. A
`CapabilityProviderConnector` contributes its manifest to discovery, every
published capability is registered as an `ActionHandler`, and the connector is
stored in the gateway registry for operator inspection and future routing
extensions.

## Native Message Routing

| Message family | Gateway behavior or response |
|---|---|
| `Handshake` | Authenticates the declared client, negotiates profiles and capabilities, creates a session, and returns `HandshakeResponse` |
| `ManifestRequest` | Filters and returns the local `Manifest` |
| `Manifest`, `HandshakeResponse` | Validates or records the remote observation and returns `EventStream` |
| `Action` | Returns terminal `ActionResult` or queued `Ack` from the runtime scheduler |
| Action status, result, list, and event requests | Authorizes the query and returns the corresponding operational view |
| Action status, list, and event responses | Records the remote observation and returns `EventStream` |
| Session view, list, close, and resume requests | Authorizes and executes the requested session operation |
| Session view, list, and resume responses | Records the remote observation and returns `EventStream` |
| `DelegationRequest` | Validates the target and returns local or authenticated remote `DelegationResult` |
| `DelegationResult` | Authenticates and settles the stored delegation graph, then echoes the settled result |
| `TransactionRequest` | Executes plan, dry-run, commit, compensate, or reconcile and returns `TransactionResult` |
| Transaction query requests | Authorizes and returns `TransactionView` or a typed error |
| Transaction results and views | Records the remote observation and returns `EventStream` |
| `ApprovalRequest`, `ApprovalDecision` | Persists the policy lifecycle transition and returns `EventStream` |
| Approval query and list requests | Authorizes and returns approval records or lists |
| Approval records and lists | Records the remote observation and returns `EventStream` |
| Callback delivery query and list requests | Authorizes and returns durable outbox records or lists |
| Callback delivery records and lists | Records the remote observation and returns `EventStream` |
| `Cancel` | Cancels eligible action or session work and returns its runtime response |
| `Heartbeat` | Returns `HeartbeatAck`; received acknowledgements become observations |
| `StreamChunk`, `Ack`, `ActionResult`, `Error` | Ingests or records lifecycle state and returns `EventStream` |
| `Escalation`, `EscalationResolution` | Persists escalation lifecycle and returns `EventStream` |
| `EventStreamRequest` | Authorizes and returns a cursor-filtered `EventStream` |
| Received `EventStream` | Records the observation and returns its recorded `EventStream` |
| `ChannelMessage`, `Conversation` | Persists channel lifecycle and returns `EventStream` |
| `ReceiptChain`, `AuditEvent`, `BatchSettlement` | Validates and stores the payload, then returns the stored payload |
| Receipt, audit, and resource queries | Authorizes and returns the matching records, list, or resource result |
| Received audit/resource query results | Records the remote observation and returns `EventStream` |

The gateway does not own product DTOs. Product-specific translation belongs in
connector crates; profile-specific translation belongs in profile crates.