Glossary

Use these terms consistently across docs, API names, web console labels, and examples.

Term	Meaning
Agent	Workload identity that performs actions through Caracal-controlled authority.
Agent app	Confidential application registered for an agent workload; one agent app backs many agent sessions.
Agent session	Coordinator record representing one agent execution or child session.
Application	Registered client in a zone; confidential applications can exchange credentials.
Audit ledger	Append-only evidence stream and database records for decisions and operations.
Caracal Operator	Governed natural-language console assistant that turns intent into reviewed, audited control-plane changes within your operator scope.
Console	Browser-based management UI served by the packaged web tier in Compose and Helm; caracal web is the local development launcher.
Control API	Optional authenticated automation surface for remote management dispatch.
Delegation edge	Bounded authority from one agent session to another.
Gateway	Reverse proxy that verifies inbound authority, exchanges with STS, and forwards to upstreams.
Grant	Access assignment connecting an application or subject to a resource and scopes.
Mandate	Short-lived JWT carrying scoped Caracal authority.
Policy	Rego content that participates in allow/deny decisions.
Policy set	Activated bundle of policy versions for a zone.
Principal	User, service, application, or agent identity participating in authority.
Provider	Credential source or upstream integration for a protected resource.
Resource	Protected API, tool, MCP server, provider target, or upstream identifier.
Root session	Originating session at the root of a delegation chain; its ID is propagated as the authority root and checked as a revocation anchor.
Runtime profile	caracal.toml or environment configuration used by caracal run and SDKs.
Service agent	Long-lived agent session started with the SDK service() handle; it holds a heartbeat lease and is retired explicitly rather than when a block exits.
STS	Security Token Service that performs token exchange and mandate issuance.
Step-up challenge	Additional approval required before STS issues authority.
Subject session	Original authenticated user or service context that initiates a chain of agent authority.
System zone	Reserved caracal.sys/ zone for the infrastructure that runs Caracal; the Operator self-governs through it and never executes against it.
Zone	Tenant and trust boundary for product state, policies, grants, sessions, and audit.

Naming Rules

• Use Caracal, not informal product nicknames.
• Use mandate for Caracal-issued JWT authority, not generic “token” when the distinction matters.
• Use web console for the browser UI and Control API for automation.
• Use top-level caracal only for runtime lifecycle, caracal run, and the caracal web development launcher.

Next Step

Use Error Codes when a service, SDK, Gateway, or verifier returns a machine-readable error.