Core Definitions and Glossary

Every schema, telemetry record, lineage edge, and Rego policy across caber-core, caber-hub, caber-run, and connector shares a single ontology. When two subsystems use the same noun for different runtime concepts, or different nouns for the same concept, lineage chains fracture and authorization rules become impossible to audit. This reference establishes the canonical definitions, identity representations, wire formats, and architectural consequences enforced across the Caber platform.

1. The Eleven Canonical Core Definitions

The platform ontology distinguishes eleven core entities. Each entity has a strict definition, a canonical runtime identity source, and explicit field bindings in telemetry spans, discovery events, and the lineage graph.

Term	Canonical Definition	Runtime Identity Source	Field in Caber Today
Principal	The human on whose behalf every request is made. Sole policy subject in Rego today.	Issuer and subject from the inbound identity token (iss + sub / email).	obo.user, baggage caber.user
Host	A physical, virtual, or containerized machine that exposes network, process execution, and filesystem APIs.	Machine id, cloud instance id, MDM device id, or SPIFFE node identity; never an IP address or DNS hostname.	host_id (`HOST-<blake2b>`). Note: api.host is an endpoint name, not a host.
Application	A deployable unit of code and configuration whose control flow is fixed in a programming language; interacts with the world only by calling and exposing APIs. An instance is one running copy.	Logical: OAuth client id, OTel service.name, SPIFFE ID path, or app registration. Instance: container id, pod UID, OS pid, or OTel service.instance.id.	Deployment id, api_host of the inbound hop, event.source.instance
Service	Synonym for Application in the logical sense (consistent with OpenTelemetry service.name).	Logical application identity (service.name).	Mapped via logical application identity
Workload	Synonym for Application instance (consistent with SPIFFE, where a running copy receives an SVID).	Instance identity (service.instance.id, pod UID, pid, or SVID).	event.source.instance
Agent	An application whose control flow is specified in natural language instructions and decided at runtime by a model, with a declared tool set and model.	Hosted agents (Bedrock, Vertex, Foundry, OpenAI Assistants, Copilot Studio) have provider assigned IDs (agentId + agentVersion / ARN, assistant_id). In process agents derive an ID from configuration (instructions, tool set, model).	caber.agent.id, caber.agent.stack (planned); api.agent.* on discovery records
Harness	The code part of an agent application that constrains what the agent can do (the execution loop, tool dispatch, permission gates, and context management). Not an application of its own.	Product name and version (for example `claude-code 2.1.300`).	api.framework
API	A named set of operations that an application or host exposes across a network, IPC, process execution, or filesystem boundary, identified by endpoint and operation. An LLM provider is an application exposing an inference API; a model is a named resource of that API.	Endpoint and operation signature.	api.* (api.id, api.host, api.path, api.resource_type)
Tool	An API operation as seen by the agent that may choose to call it (subset of API). An MCP server is an application exposing an API; a Bash command is a host process execution API; a file read is a host filesystem API; a plugin is an API exposed by the harness.	Tool name (gen_ai.tool.name), linked to the target api.* record.	tool.name (planned), api.agent.tool.name, recorded as api.*
Caller / Callee	The identity that issued a request versus the identity that received it. The Principal is always the root Caller; anything except a Principal can be a Callee. The agent stack is the Caller chain between the Principal and the current Callee, filtered to agents.	Root human identity plus the ordered chain of intermediate callers and span parents.	caber.user (root), caber.agent.stack (planned), caber.parent_span_id
Session	An interaction identified by the application itself (a conversation, WebSocket connection, or thread); recorded only when one exists, never fabricated.	Native session or connection token supplied by the application or protocol.	event.session_id, connection_id

2. Detailed Entity Specifications

2.1 Principal

A Principal is always a human user. Service accounts, OAuth client credentials, and agent identities are never Principals; they are Applications or Agents acting on behalf of a Principal.

• Why this matters: In pycaber, Rego policies evaluate data clearance against the Principal (obo.user / caber.user). If an automated pipeline or subagent invokes an external tool, the root human Principal remains attached across every hop via W3C baggage (caber.user) and the lineage graph's On Behalf Of (OBO) resolution.
• Identity extraction: Derived from verified OIDC/JWT claims (iss and sub or verified email) at the ingress proxy (connector or caber-hub) or workstation identity (caber-run).

2.2 Host

A Host is the physical, virtual, or containerized machine boundary that provides an operating system kernel, network stack, process execution interface, and local filesystem.

• Identity vs. Endpoint Name: A Host's identity (host_id, formatted as `HOST-<blake2b>`) is computed deterministically from stable machine attributes (OS machine UUID, cloud instance ID, MDM hardware serial, or SPIFFE node attestation). It is never an IP address or a DNS hostname.
• Disambiguating host_id and api.host: In telemetry records, host_id identifies the machine where a process or caber-run supervisor executes. By contrast, api.host is the network authority or logical endpoint name of an API (for example, api.anthropic.com or local.bash).

2.3 Application, Service, and Workload

An Application is a deployable unit of deterministic code and configuration written in a traditional programming language (Rust, Python, TypeScript, Go, Java). Its control flow is fixed at compile or deploy time, and it interacts with its environment exclusively by exposing and calling APIs.

• Service (Logical Application): Refers to the logical application definition across all replicas, matching OpenTelemetry service.name, an OAuth client registration, or a SPIFFE ID path.
• Workload (Application Instance): Refers to a single running OS process, container, or Kubernetes pod replica, matching OpenTelemetry service.instance.id or a concrete SPIFFE X.509/JWT SVID.

2.4 Agent and Harness

An Agent is a specialized Application whose control flow is specified in natural language instructions (system prompts, skills, persona rules) and decided dynamically at runtime by a foundation model over a declared tool set.

• Hosted Agents vs. In Process Agents: Hosted agents (AWS Bedrock Agents, Google Vertex AI Agents, Azure AI Foundry Assistants, OpenAI Assistants, Microsoft Copilot Studio) carry provider assigned identifiers (agentId, agentVersion, assistant_id, or cloud ARN). In process agents (LangGraph, CrewAI, AutoGen, or custom loops running inside caber-run) derive a deterministic identity from their configuration tuple (instructions hash, declared tool set, and backing model).
• Harness: Every Agent executes inside a Harness (api.framework), which is the deterministic code layer that runs the turn loop, parses model tool call requests, enforces local permission gates, and manages context windows (for example, `claude-code 2.1.300`, `codex-cli`, or `langgraph`). The Harness is part of the agent application, not a separate node in the caller chain.

2.5 API and Tool

An API is any named set of operations exposed across a network socket, inter process communication (IPC) channel, OS process execution interface (execve), or filesystem boundary.

• LLM Providers as APIs: An LLM provider (such as Anthropic, OpenAI, or AWS Bedrock Runtime) is an Application that exposes an inference API. The foundation model itself (such as `claude-3-7-sonnet` or `gpt-4o`) is a named resource parameter of that inference API, not an Agent or a Principal.
• Tool as a Role: A Tool is not a distinct infrastructure primitive; it is an API operation viewed from the perspective of an Agent that has been granted permission to invoke it. When an agent invokes a tool (gen_ai.tool.name / api.agent.tool.name), the underlying execution is always recorded and governed as an API call (api.*).

2.6 Caller, Callee, and the Agent Stack

Every interaction in Caber is a directed request from a Caller to a Callee.

• Root Caller Rule: The Principal is always the root Caller at the base of the causal tree (caber.user). A Principal initiates sessions and requests, but nothing in the system ever calls a Principal as a Callee.
• Agent Stack: When an Agent delegates a subtask to a subagent (via invoke_subagent, MCP tool delegation, or A2A HTTP calls), the intermediate callers form an ordered chain between the Principal and the active Callee. Filtering this chain to Agent identities produces caber.agent.stack, while caber.parent_span_id preserves the exact causal parent hop.

2.7 Session

A Session (event.session_id or connection_id) groups a sequence of turns, messages, or requests that the application itself treats as a stateful conversation or persistent transport connection.

• No Fabricated Sessions: If an application protocol or agent harness provides a native conversation ID, thread ID, or WebSocket connection ID, Caber records it verbatim. If a call is stateless and carries no application session identifier, Caber leaves the session field empty rather than synthesizing an artificial session ID.

3. Four Architectural Consequences

The eleven definitions above are not merely descriptive; they directly govern how pycaber, pycaber, and pycaber construct nodes, edges, and policy inputs:

1. Tool Is a Role, Not a Separate Entity Class: Every tool invocation resolves to a concrete API operation on a target Application or Host:
   • An MCP server is an Application exposing a JSON RPC API over stdio or HTTP (api.resource_type = "mcp").
   • A Bash command or script is a Host process execution API (api.resource_type = "bash" or "script").
   • A file read or write is a Host filesystem API (api.resource_type = "filesystem").
   • A plugin is an API exposed directly by the agent Harness (api.resource_type = "plugin").
2. Harness Is Part of the Agent Application: Because the harness (api.framework) is the deterministic execution loop of the agent application rather than an independent service hop, Caber records the harness as metadata on the Agent or API discovery event rather than inserting a spurious intermediate Application node into the lineage graph.
3. LLM Providers and Models Are Inference APIs: Calling an LLM endpoint is an outbound API call where the model identifier is a resource attribute. Only the system whose control flow is driven by that model's responses (combined with system instructions and declared tools) is classified as an Agent.
4. Principal Is Always Root Caller, Never Callee: Authorization policies can always resolve a deterministic root human subject (obo.user / caber.user) regardless of call depth, subagent fan out, or asynchronous tool execution.

4. CORI (Caber Object Resource Identifier) Specification

Every document, object store blob, and intercepted API payload indexed by Caber is assigned a canonical CORI (Caber Object Resource Identifier), implemented in pycaber.

The {source} prefix is validated at mint time by validate_source_token and derived from connector labels by derive_source_token in pycaber:

• Length: Must be between 1 and 10 characters inclusive (CORI_SOURCE_TOKEN_MAX_LEN = 10).
• Character Set: Strictly ASCII lowercase alphanumeric characters (a through z, 0 through 9). Uppercase characters, hyphens, underscores, spaces, and punctuation are rejected at mint time.
• Role Prefix Letter: The first character encodes the storage role:
  • g (Global Shared Storage role): Reserved for Caber's internal intercepted payload storage (gss).
  • c (Customer Source role): Used for all customer owned document repositories and object stores (cs3aws, cgdrive, csharept, etc.).

6. Platform Glossary

• Sub Sentence Containment: Caber's ability to detect when a small fragment of a source document (as short as a single clause or sentence) appears inside a larger outbound API payload or LLM response, powered by token level roaring bitmap postings in pycaber.
• Roaring Bitmap Inverted Index: A lock free, memory mapped inverted index where each token maps to a compressed 32 bit Roaring Bitmap (RoaringBitmap) of integer document IDs and chunk offsets, enabling microsecond set intersections across millions of chunks.
• Semantic Fingerprint: A compact representation of a text chunk's rarest tokens (weighted by corpus IDF) used by pycaber to candidate filter source documents before running exact positional verification.
• Document Cluster: A subgraph of documents and chunks connected by SIMILAR_TO, CONTAINS, or DERIVED_FROM edges, representing version history, copy paste forks, and template derivatives across enterprise storage.
• Policy Follows Data: Caber's core zero trust governance principle: instead of maintaining static allowlists per API endpoint or per tool, sensitivity tags and access rules attach to the content itself and propagate automatically across every copy, edit, RAG retrieval, and agent tool call.
• On Behalf Of (OBO) Propagation: The mechanism in pycaber and pycaber that binds every asynchronous background task, MCP tool call, and subagent invocation back to the originating human Principal (obo.user / caber.user).
• Governance Ledger: The immutable, hash chained audit log (AuditRecord) recording the input CORIs, Principal identity, active agent stack, evaluated Rego rules, and final authorization verdict (Allow, Deny, Redact, Alert) for every governed API transaction.
• Global Shared Storage (gss): The internal content addressed object store bucket (shared-storage) where connector and caber-hub persist raw intercepted API request and response payloads under gss⋊⋉... CORIs.
• Caber Core (caber-core): The multi process distributed Rust runtime deployed in External and Internal enterprise environments, exposing gRPC and HTTP ingestion, roaring index lookup, graph construction, and OPA governance services.
• Caber Hub (caber-hub): The single binary, in process consolidation of all five Caber pipeline stages (bins/caber-hub), designed for zero dependency local workstation deployment (Standalone) or single node sidecar operation.
• Caber Run (caber-run): The workstation CLI wrapper (bins/caber-run) that launches an AI coding harness (such as claude-code or codex), injects transparent proxy and telemetry settings, captures local process executions (bash / script), and forwards traffic to caber-hub or connector.
• Connector (connector): The lightweight Rust forward and reverse proxy (bins/connector) that intercepts HTTP/HTTPS, LLM inference, MCP, and object store traffic at wire speed, streams payloads to Global Shared Storage, and enforces inline governance verdicts.