RFC: Companion Diagrams: Hook + Plugin System Lifecycle Flows

Status: Diagram companion aligned to implemented foundation Last updated: 2026-04-08 Related RFC: rfc-hook-plugin-system.md Related Example: rfc-hook-plugin-system-cid-resolution-example.md

1. Purpose

This document provides Mermaid diagrams for the hook and plugin system described in the RFC.

The diagrams are illustrative and focus on:

• the control-plane to gateway runtime relationship
• the in-process plugin execution model (native Go + WASM)
• the host-managed capability model
• the synchronous request lifecycle hooks
• the asynchronous request.end lifecycle flow

2. High-Level System Architecture

flowchart LR
    subgraph CP[Control Plane]
        PD[Plugin Definitions]
        PA[Plugin Artifacts]
        PS[Signed Plugin Snapshots]
        ACT[Manual Snapshot Activation]
    end

    subgraph GW[Gateway Runtime]
        PM[PluginManager]
        HE[HookEngine]
        CB[CapabilityBroker]
        PE[PremadeExecutor]
        WE[WASMExecutor]
        EW[EndHookWorker]
    end

    subgraph P[Plugins]
        AUTH[builtin.authorization]
        OPA[OPA/Rego Plugin]
        VT[Intent / VirusTotal Plugin]
        CW[Custom WASM Plugins]
    end

    subgraph HostCaps[Host-Managed Capabilities]
        CID[ResolveCID]
        RB[ReadRequestBody]
        HTTP[DoHTTPRequest]
        SEC[Secret Ref Injection]
    end

    subgraph Data[Internal / External Systems]
        BS[Embedded CID Router / Blob Store]
        OBJ[Artifact Object Storage]
        REG[Trusted Agent Registry]
        EXT[External HTTPS Systems]
        AUD[Audit + Metrics + Logs]
    end

    PD --> PS
    PA --> PS
    ACT --> PS
    PS --> PM
    PM --> HE
    PM --> PE
    PM --> WE
    HE --> PE
    HE --> WE
    PE --> AUTH
    PE --> OPA
    PE --> VT
    WE --> CW
    PE --> CB
    WE --> CB
    CB --> CID
    CB --> RB
    CB --> HTTP
    CB --> SEC
    CID --> BS
    PM --> OBJ
    HTTP --> EXT
    SEC --> HTTP
    AUTH --> REG
    HE --> AUD
    CB --> AUD
    EW --> AUD

3. Synchronous Request Lifecycle

sequenceDiagram
    autonumber
    participant Client
    participant Gateway
    participant HookEngine
    participant Plugin as Plugin Chain
    participant CapBroker as CapabilityBroker
    participant Verifier
    participant Registry as Trusted Registry
    participant Upstream as LLM Provider
    participant Audit

    Client->>Gateway: Incoming proxied request
    Gateway->>Gateway: Resolve route/provider metadata from gateway path
    Gateway->>HookEngine: request.start
    HookEngine->>Plugin: Execute request.start plugins in order
    Plugin->>CapBroker: Optional ResolveCID / ReadRequestBody / DoHTTPRequest
    CapBroker-->>Plugin: Policy-gated capability results
    Plugin-->>HookEngine: HookDecision / emitted events / tags
    HookEngine-->>Gateway: Continue or deny

    Gateway->>Verifier: Signature + attestation + replay + registry verification
    Verifier->>Registry: Resolve agent/key state
    Registry-->>Verifier: Trusted lookup result
    Verifier-->>Gateway: Verified identity or deny

    Gateway->>HookEngine: proxy.pre
    HookEngine->>Plugin: Execute proxy.pre plugins in order
    Plugin->>CapBroker: Optional ResolveCID / ReadRequestBody / DoHTTPRequest
    CapBroker-->>Plugin: Policy-gated capability results
    Plugin-->>HookEngine: HookDecision / emitted events / tags
    HookEngine-->>Gateway: Continue or deny
    Gateway->>Upstream: Proxy request to provider
    Upstream-->>Gateway: Response / stream headers

    Gateway->>HookEngine: proxy.post
    HookEngine->>Plugin: Execute proxy.post plugins in order
    Plugin->>CapBroker: Optional DoHTTPRequest before commit
    CapBroker-->>Plugin: Policy-gated capability results
    Plugin-->>HookEngine: HookDecision / emitted events / tags
    HookEngine-->>Gateway: Commit response or deny pre-commit

    Gateway->>Audit: Persist request + sync hook events
    Gateway-->>Client: Final response
    Gateway->>HookEngine: Enqueue request.end

4. Detailed Hook Ordering and Decision Points

flowchart TD
    A[Request enters gateway] --> B[Route / provider recognition]
    B --> C[request.start]
    C --> D{Any enforcement plugin denies?}
    D -- Yes --> E[Return deny envelope]
    D -- No --> F[Core verify]
    F --> G{Verification fails?}
    G -- Yes --> E
    G -- No --> H[Finalize upstream metadata]
    H --> I[proxy.pre]
    I --> J{Any enforcement plugin denies?}
    J -- Yes --> E
    J -- No --> K[Proxy upstream request]
    K --> L[Receive response or stream headers]
    L --> M[proxy.post]
    M --> N{Any enforcement plugin denies before commit?}
    N -- Yes --> E
    N -- No --> O[Persist request + sync hook events]
    O --> P[Send response to client]
    P --> Q[request.end async observability]
    Q --> R[Durable retry / DLQ / event persistence]

5. Capability Flow for a Plugin Invocation

flowchart LR
    PI[Plugin Invocation] --> CG{Capability granted in snapshot?}
    CG -- No --> DENY[Return host capability error]
    CG -- Yes --> TYPE{Capability type}

    TYPE -- cid.resolve --> CIDP[Validate grant and max_bytes]
    CIDP --> CIDR[Read from gateway blob store]
    CIDR --> RES1[Return CIDResolution]

    TYPE -- request.body.read --> RBP[Enforce max readable bytes]
    RBP --> RBR[Read full request body]
    RBR --> RES2[Return RequestBodyRead]

    TYPE -- http.request --> HP[Validate destination / method / timeout / size policy]
    HP --> HS[Dispatch outbound request]
    HS --> HR[Dispatch outbound HTTPS request]
    HR --> RES3[Return OutboundHTTPResponse]

    DENY --> AUD[Capability telemetry + audit]
    RES1 --> AUD
    RES2 --> AUD
    RES3 --> AUD

6. Asynchronous request.end Flow

sequenceDiagram
    autonumber
    participant Gateway
    participant HookEngine
    participant Queue as Durable End Queue
    participant Worker as EndHookWorker
    participant Plugin as request.end Plugins
    participant CapBroker as CapabilityBroker
    participant External as External HTTPS Systems
    participant Store as Event Store / DLQ

    Gateway->>HookEngine: request.end event
    HookEngine->>Queue: Enqueue durable work item
    HookEngine-->>Gateway: Return immediately

    Worker->>Queue: Dequeue item
    Worker->>Plugin: Execute request.end observability plugins in order
    Plugin->>CapBroker: Optional ResolveCID / ReadRequestBody / DoHTTPRequest
    CapBroker->>External: Optional outbound HTTPS
    External-->>CapBroker: Response
    CapBroker-->>Plugin: Capability result
    Plugin-->>Worker: HookDecision / emitted events / tags (deny recorded only)
    Worker->>Store: Persist async hook events

    alt Success
        Worker->>Store: Mark success
    else Retryable failure
        Worker->>Queue: Requeue with bounded retry
    else Terminal failure
        Worker->>Store: Write DLQ entry
    end

7. Snapshot and Runtime Activation Flow

flowchart LR
    A[Create / update plugin definition] --> B[Upload signed artifact through control-plane]
    B --> C[Store immutable object ref + metadata]
    C --> D[Create immutable snapshot]
    D --> E[Manual activate snapshot]
    E --> F[Gateway poll current snapshot metadata]
    F --> G[Open referenced artifacts from object storage]
    G --> H[Verify digest + signature]
    H --> I[Compile / load executors]
    I --> J[Persist verified last-known-good cache]
    J --> K[Validate hooks + config + capability policy]
    K --> L{Validation passes?}
    L -- No --> M[Keep last-known-good snapshot]
    L -- Yes --> N[Atomically swap active snapshot]
    N --> O[New requests use new snapshot]

8. Notes

• These diagrams assume the current RFC direction: in-process native Go plus WASM execution with host-managed capabilities.
• They intentionally do not model remote sidecar or RPC plugin execution, which is deferred.
• proxy.post is shown only at the response or stream-headers stage because per-chunk streaming hooks are out of scope for V1.
• Artifact uploads are proxied through control-plane, while gateway reads artifacts directly from object storage using service credentials.