trustgraph/specs/websocket/channels/socket.yaml

address: /api/v1/socket
description: |
  Primary WebSocket channel for all TrustGraph services.

  This single channel provides multiplexed access to:
  - Global services (IAM)
  - Workspace-scoped services (config, flow, librarian, knowledge, collection-management)
  - Flow-scoped services (agent, RAG, embeddings, queries, loading, etc.)

  ## Authentication

  The handshake is accepted unconditionally.  The client must send a
  bearer token as the first frame after connecting (in-band auth).
  The gateway resolves the token to an identity and workspace.  All
  subsequent requests execute within that workspace context.

  ## Multiplexing

  Multiple requests can be sent concurrently over this channel. Each request includes
  a unique `id` field that is echoed back in responses for correlation.

  ## Message Flow

  1. Client connects and sends bearer token as first frame (authentication)
  2. Client sends requests with unique `id`, `service`, optional `flow`, and `request` payload
  3. Server processes request asynchronously
  4. Server sends response(s) with matching `id` and either `response` or `error`
  5. For streaming services, multiple responses may be sent with the same `id`

  ## Service Routing

  Messages are routed to services based on:
  - `service`: Service identifier (required)
  - `flow`: Flow ID (required for flow-scoped services, omitted for workspace-scoped and global services)

messages:
  request:
    $ref: '../components/messages/ServiceRequest.yaml'
  response:
    $ref: '../components/messages/ServiceResponse.yaml'
  error:
    $ref: '../components/messages/ServiceError.yaml'