Skip to main content

Request lifecycle

Every request that hits the Trinitite control plane goes through the same skeleton. This page visualizes that skeleton end-to-end and calls out the invariants that hold for every request.

The canonical sequence​

A governed-chat request is the representative case because it touches every layer: auth, RBAC, service, port, adapter, external system, audit log, and receipt chain. Everything else is a variation on this shape.

The invariants (hold for every request)​

  1. Authentication resolves a principal and derives org-scope. A session token, an API key, or an NHI credential all resolve to the same principal shape; the organization is derived from the credential, never from the request body. There is no way to "post" into another org.
  2. Permissions are enforced before the controller runs. The PermissionsGuard checks the required permission (e.g. guardians:read) against the resolved principal; a 403 forbidden (or entitlement_denied) short-circuits before any domain logic runs.
  3. The domain service talks to ports, not adapters. Hexagonal architecture: the service depends on a port interface (IInferencePort); the adapter (HttpInferenceAdapter) is injected at runtime. This is what lets the same service run against a local inference pod, Runpod, or a self-hosted GPU.
  4. Every governed call produces one normalized verdict. The contract is passed, corrected, blocked, masked, HiTL, or failed, regardless of surface.
  5. Every governance event is persisted and hash-chained. The audit row carries the prior hash; the new row's chain_hash is H(prev_hash ‖ row). Altering any past row breaks the current hash. This is the Glass Box Ledger append.
  6. The response carries the verdict and the receipt. The caller branches on the verdict; the receipt (ledger_id, policy_hash, chain_hash, determinism_mode) is the evidence.

What this means for you​

Because the skeleton is identical across all 200+ control-plane controllers, you can learn the platform once: trace any endpoint through these eight steps and you know where the auth check lives, where the permission is enforced, where the external call happens, and where the audit row is written. The API Reference documents the per-endpoint variations on top of this skeleton.

→ Platform topology: the services this path runs through. → Architecture: the Guardian evaluation at step 9. → Verdict vocabulary: the six verdicts and the receipt.

Last updated on