# How AIP Works

AIP turns a request into a governed, observable unit of work. The protocol does
not assume that work finishes in one HTTP response or that the caller and the
system performing the work share the same technology stack.

## The Request Path

```mermaid
sequenceDiagram
    participant C as Client or Agent
    participant G as AIP Gateway
    participant P as Policy and Identity
    participant R as Durable Runtime
    participant X as Connector or Native Handler

    C->>G: Discover manifest
    G-->>C: Capabilities and contracts
    C->>G: Action envelope
    G->>P: Authenticate and authorize
    P-->>G: Allow, deny, or require approval
    G->>R: Reserve action and idempotency key
    R->>X: Invoke with trusted execution context
    X-->>R: Chunks, result, or uncertain outcome
    R-->>C: Result, stream, or callback
    C->>G: Query status, events, receipts
    G-->>C: Durable operational view
```

## 1. Discovery

A participant publishes a manifest. Each capability includes an input schema
and may include output, risk, side-effect, approval, idempotency, data, service
level, transaction, and compensation contracts.

Discovery lets a caller answer two questions before sending work:

- Can this participant perform the operation?
- Under what safety and lifecycle conditions will it perform it?

## 2. Authentication and Trusted Context

An envelope may contain a `from` principal, but that field is a claim. The edge
authenticates the transport identity and creates trusted execution context. AIP
then resolves tenant membership, credential references, scopes, and delegated
authority from server-controlled data.

Connectors receive this frozen context. They must not trust a tenant id,
credential handle, or approver identity merely because it appeared in user
input.

## 3. Action Admission

The gateway validates the envelope, capability contract, input schema,
invocation mode, deadline, idempotency rules, and policy decision. Admission is
atomic with the handler catalog: a manifest cannot advertise a callable
capability unless an admitted handler owns it.

The runtime then reserves the action. Duplicate idempotency keys follow the
capability's declared collision policy; they are not treated as new work.

## 4. Execution

An action can be synchronous, asynchronous, or streaming.

- **Synchronous** returns a final result in the request path.
- **Asynchronous** returns acceptance and continues through a durable worker.
- **Streaming** emits ordered chunks before a terminal result.

Cancellation is cooperative and capability-specific. The runtime records the
request even when a provider cannot confirm cancellation immediately.

## 5. Human Approval

When policy requires approval, the runtime creates a durable approval request
and parks the action. A trusted authority resolver verifies the approver and
the applicable rule. An approved decision resumes the same governed action;
the caller does not submit a replacement operation with different input.

## 6. Transactions

Sensitive mutations may use `dry_run`, `plan`, `commit`, `compensate`, or
`reconcile`. A plan binds the capability, input hash, identity, policy, and
transaction id. Commit is accepted only for the same immutable operation.

If a provider may have committed but the response was lost, the runtime records
`outcome_unknown`. It reconciles provider state before retrying or compensating.

## 7. Delegation

Delegation creates a child action linked to a parent action. AIP carries the
delegation scope and chain across the trust boundary, routes the request to an
authenticated peer, and correlates the child's result with the parent graph.
The child is still a normal AIP action with policy, lifecycle, cancellation,
events, and receipts.

## 8. Evidence and Recovery

The runtime stores lifecycle events, stream chunks, approval state,
transactions, callback attempts, and receipt chains. Clients and operators use
query APIs instead of inferring state from logs or retrying blindly.

This separation is central to AIP: the response tells a caller what happened in
one exchange; the operational read model tells authorized readers what the
system currently knows.