---
title: "Glossary"
description: "The domain vocabulary Obol uses exactly this way in code, docs, and the dashboard."
---

These terms are used exactly this way in code, documentation, and the dashboard. The canonical list is `docs/GLOSSARY.md` in the Obol repository; if a pull request introduces a new domain noun, it gets a row there.

<Info>
Precision here is load-bearing. Several pairs of terms look interchangeable and are not: effect claim is not evidence trust, evidence trust is not a verification conclusion, a capability is not a stage capability token, and a sandbox is not a verification result.
</Info>

## Planes and distribution

| Term | Meaning |
|---|---|
| **Obol** | The product; named for the coin placed with the dead to pay Charon for passage — the toll paid at a gateway. |
| **Data plane** | `apps/gateway` (Rust): the hot path serving `/v1/*` and `/mcp`. |
| **Control plane** | `apps/control` (Python): tenants, keys, OAuth, policy compile and publish, approvals, billing. |
| **Snapshot** | The compiled per-workspace bundle (keys, connections, tools, Cedar policy set and entities) that control publishes to Redis and the gateway evaluates from. The only way state reaches the data plane. |
| **Environment (env)** | `dev`, `stage`, or `prod` at the workspace level. A dev key can never reach a prod connection. |

## Identity and credentials

| Term | Meaning |
|---|---|
| **Virtual key** | An Obol-minted credential (`ob_live_…` / `ob_test_…`) scoped to a workspace, models, tools, budget, rate limits, env, and expiry. The only credential an agent ever holds. Stored hashed; the secret is shown once. |
| **Envelope encryption** | Per-connection AES-256-GCM data key (DEK) wrapped by a KMS-held key (KEK). Ciphertext in Postgres; decrypt only inside the gateway process. |
| **BYOK** | Bring-your-own-key: the customer's model-provider key, vaulted and injected outbound. Obol resells nothing by default. |
| **BYOA** | Bring-your-own-app: a customer-owned OAuth app, so vendor tokens live in their cloud project. The enterprise custody option. |
| **Auth profile** | Pinned, snapshot-resident declaration of how a connection authenticates (OAuth2 endpoints plus client id, API-key scheme, or federated catalog session URL). Callers cannot supply the token or the session URL. |
| **Credential capability** | Short-lived, single-use, control-minted JWT with a dedicated audience (`obol-gateway-cred-exchange` / `refresh` / `seal` / `catalog-session`) authorizing one gateway plaintext operation. |
| **Stage capability token** | The control-minted, short-lived, single-use, nonce-bound token authorizing one gateway readback stage or OAuth credential operation. Always written in full — never bare "capability", which names the routing contract below. |
| **Hybrid custody** | A connection where Obol vaults its own read-only vendor credential alongside a broker-held write credential, enabling a direct `gateway_observed` readback. The only path by which a federated write reaches `verified`. **Deferred to phase 2 (`docs/PRD.md` §12) — it does not ship**, and it requires amending the connection contract, which today holds either an Obol-encrypted credential or a federated upstream reference, never both. Would be possible only where a broker permits token extraction. |

## Connectors and custody

| Term | Meaning |
|---|---|
| **Connector** | A namespaced integration definition enabled in a workspace: native builtin, imported OpenAPI, remote MCP, or federated catalog source. One connector can have many connections. |
| **Connector bundle** | The immutable, versioned contract compiled from a connector source: auth profile, endpoint allowlists, tool schemas, `EffectSpec`, optional `VerificationPlan`, webhook definitions, digest, and publisher. Under ADR-0020, enabling a shared publisher artifact materializes a workspace-qualified bundle; runtime metadata is never trusted outside it. **That materialization is unbuilt** — there is no `connector_bundles` table, and control reads a reviewed pack straight off disk (`services/tools.py::load_bundle` → `packages/connectors/<slug>/bundle.json`). Bundle *validation* exists, in Rust (`obol-types/src/bundle.rs`). |
| **Connection** | A workspace's instance of a connector: status, scopes, custody mode, and either an Obol-encrypted credential or a federated upstream reference. |
| **Connector tier** | The execution and trust class recorded in snapshots and receipts: `native`, `trusted_worker`, or `federated`. A native route is gateway-observed, not automatically verified; policy may forbid a tier or require a minimum verification capability. |
| **Worker** | Reserved design (ADR-0024, parked by ADR-0058), not a shipped deployable: a reviewed, out-of-process Python planner or normalizer in `apps/connectors` for messy first-party vendors. ADR-0024 specifies that the gateway would validate its bounded request plans and perform credentialed HTTP, so the worker would never see a credential. **That protocol is not implemented.** The shipped `WorkerExecutor` still runs ADR-0014's `x-obol-upstream-authorization` hand-off; no worker exists to receive it. A worker mints no receipt and assigns no evidence trust on either path. |
| **Federated connector** | A remote MCP server or external catalog backend that owns its underlying vendor connection. Obol authorizes and receipts the call but treats its result as untrusted or broker-attested evidence. |
| **Catalog provider** | An optional federated backend (Nango, Composio) that lists and authenticates long-tail APIs. Never Obol's policy, vault, or receipt authority. Each workspace brings its own broker credential; platform-wide pooled broker keys are forbidden. |
| **Catalog broker** | A federated backend supplying connector breadth and holding the customer's vendor credential. A catalog and credential-custody vendor, never an execution, idempotency, or verification authority. Every broker account is workspace-scoped; pooled broker accounts and pooled broker OAuth apps are forbidden. |
| **Broker reference** | The workspace- or account-scoped pointer a federated connection stores instead of a vendor secret: catalog provider, integration id, upstream connection id, optional MCP URL. |
| **Namespacing** | Tools from every connector tier are exposed as `<connector>.<tool>` (`stripe.create_refund`) so native, worker, and federated catalogs cannot collide. |
| **Progressive tools** | Key mode exposing only `search_tools` and `call_tool` instead of the full catalog, keeping schemas out of the model's context window. |
| **Destructive tool** | A tool flagged as state-changing with real-world blast radius (refund, delete, send SMS, payout change). Subject to approval policies in prod by default. |

## Capabilities and routing

| Term | Meaning |
|---|---|
| **Capability** | A published, versioned, content-addressed contract naming a job (`cap.web.scrape`) with one or more candidate provider operations. Eligibility across native and federated bindings does not certify interchangeability (ADR-0063). It defines a canonical input and output schema, a closed feature vocabulary, a small `guaranteed_outputs` core, a larger provider-dependent surface, declared semantics, and an `EffectSpec`. Exposed as a namespaced tool under the reserved `cap` connector prefix. Cedar never authorizes a capability — only the concrete tool it resolves to (ADR-0027). Distinct from a stage capability token. |
| **Capability binding** | The mapping from one concrete tool to one capability: declared coverage, declarative input and output transforms, error map, limits, cost hint, and compliance block. A binding introduces no new execution path — its target is an existing tool on an existing connector bundle at an existing tier. Native and federated bindings are eligible by default (ADR-0063). Missing conformance evidence does not block eligibility; actual connection, permission, request, and evidence constraints still apply. |
| **Capability card** | What the resolver returns: a capability, its input schema, and how many providers this key could use. Never which providers, never a price, never a score. |
| **Coverage** | A binding's machine-readable claim over the capability's feature vocabulary: `supported`, `unsupported`, or `emulated` with a fidelity of `exact`, `coarsened`, `approximate`, or `synthesised`. Generated from passing conformance fixtures, never asserted. Acts as a hard routing filter. |
| **Feature token** | A member of a capability's closed vocabulary naming one optional behaviour (`scrape.render_js`, `scrape.no_js`). Coverage must be symmetric: being able to do a thing and being able to refrain from it are different tokens. |
| **Requirement level** | How strictly one input field must be honoured: `require` (hard routing filter), `prefer` (soft rank), or `best_effort`. A field the caller explicitly set defaults to `require` — a silent parameter drop in a tool call is a correctness failure, not a cost optimisation. |
| **Route policy** | Versioned, digested per-workspace routing configuration in the snapshot: preference order, allow and deny lists, fallback permission, score weights, hard filters, minimum evidence trust, and compliance profile. A request-level preference may only narrow it, never widen it. |
| **Route qualifier** | Workspace-authored rule (`only` / `ignore` / `pin` / preferred auth, surface, and catalog source) naming which Nango, Composio, or native tools may serve a `cap.*` call. Published in the snapshot; a per-call `route` object may only narrow it. |
| **Route decision record** | The gateway-written explanation of one selection, attached to the receipt: effective weights, every candidate with its inputs, arithmetic terms and rank, closed-enum exclusion reasons for filtered candidates, the chosen provider, the route reason, the per-attempt trail, and the algorithm and snapshot versions it ran under. A routing decision that cannot be explained from it does not ship. |
| **Route provenance** | The gateway-written block on a routed result naming the provider, connection, capability and binding versions, route reason, evidence trust, and any coverage degradations. Written from the dispatch observation, never by a connector, worker, or catalog. |
| **Degradation** | A `prefer`- or `best_effort`-level feature a selected provider could not honour. The dependent output field is explicitly null and a `degraded` entry names the field, the feature, and the fidelity. Never a plausible-looking substitute value, and never an unexplained null. |
| **Lane** | Which custody a route runs under — Obol-custodied or federated. A solid edge means Obol's own connection reached the vendor; dashed means it reached a broker. |
| **Intent digest** | SHA-256 of a caller's stated intent. The prose is stripped so it cannot reach a vendor; the digest lets a decision be correlated with it and provably cannot influence selection. |

## Invocation, evidence, and receipts

| Term | Meaning |
|---|---|
| **Invocation** | One logical authenticated tool call owned by the gateway, identified before visibility and admission, retaining one invocation ID, request hash, and workspace-scoped idempotency key across approval and safe retries. Authorization, dispatch, and verification states remain separate. |
| **EffectSpec** | Required declarative tool contract for effect kind, outbound idempotency binding, dispatch-status classification, safe upstream-ID selection, bounded response assertions, and evidence policy. It describes an effect without embedding connector business logic in the gateway. |
| **DispatchObservation** | Executor-neutral, non-serializable facts observed during one attempt: dispatch state and certainty, evidence trust, numeric vendor status, safe IDs, response digest, typed error, and temporary selected evidence. Input to verification — not a receipt, and not a verification conclusion. |
| **InvocationReceipt** | A versioned gateway-minted revision in one invocation history. It separates authorization, dispatch, evidence-trust, and verification summaries, and stores digests rather than raw evidence or credentials. It proves only what its named evidence class supports. |
| **InvocationAuditEnvelope** | The exact-v1, checked durable fact pairing one `InvocationReceipt` with its corresponding `VerificationEvent`. The gateway acknowledges it in Redis before exposing receipt metadata, terminal replay, or a usage receipt link. It does not increase the receipt's evidence trust. |
| **Verification plan** | A future optional immutable extension to `EffectSpec` declaring uniquely identified immediate, readback, and webhook stages, deadline, correlation, and acceptable effect-claim and evidence-trust combinations. Its digest is pinned to the invocation. |
| **VerificationEvent** | A redacted, append-only, invocation-correlated result of gateway evaluation. Each accepted evidence item gets an event; a new receipt revision is minted only when the public summary changes. It contains digests and safe metadata, not raw compared values or credentials. |
| **Webhook evidence event** | Immutable, pre-correlation record of a signature-validated webhook containing safe IDs, provenance, digest, and bounded outcomes — not a receipt or a conclusion. |
| **Evidence trust** | Provenance assigned by Obol, not by payload claims: `gateway_observed`, `vendor_signed`, `connector_attested`, `broker_attested`, or `untrusted`. Broker-attested requires a pinned workspace-scoped broker identity; untrusted evidence can never satisfy verification. |
| **Effect claim** | What evidence says occurred: accepted, persisted, or delivered. Independent of evidence trust and of the verification conclusion. |
| **Broker attestation** | A broker-to-Obol signed statement over an execution, validated against a pinned workspace-scoped key. `attestation: signed_assertion` when the broker signs the vendor request digest, status, and object id; `attestation: channel` when only the transport identity is authenticated. Obol authenticating *to* a broker is never an attestation. A signed assertion proves non-repudiation, not correctness. |
| **Evidence ceiling** | The strongest evidence trust a binding can achieve, computed from custody mode, verification-plan stages, and whether a broker identity or vendor webhook subscription is actually provisioned — proved by conformance fixtures, never asserted by a publisher. Part of the capability contract, not an attribute of the winning provider. |
| **Evidence floor** | The minimum evidence ceiling a route must achieve, derived from effect class and environment rather than configured. A hard routing filter, on by default, so cost can never silently buy weaker proof. Lowering it is an explicit recorded workspace decision carried on the receipt. |
| **Idempotency propagation** | Whether a binding can carry Obol's idempotency key through to the vendor. `none` on federated routes, because Obol does not construct the vendor request. Gateway-side idempotency is unconditional regardless; propagation is declared honestly and is policy-deniable for production writes. |

## Policy and approvals

| Term | Meaning |
|---|---|
| **Policy** | Cedar source authored per workspace, validated against the schema in `packages/cedar` and compiled into the snapshot. The authorization of record. |
| **Prefilter** | The cheap CEL layer deciding *visibility* (what appears in `tools/list`, env match) before Cedar decides *permission*. |
| **Approval** | A held destructive invocation: the gateway returns `approval_required`, a ticket lands in the inbox, and approval resumes the same invocation and idempotency key exactly once. |
| **Approval policy** | Control-owned rules governing which humans may review a held action, matched by concrete tool, environment, role, or named member. Explicit reviewer deny wins; no matching allow grants no review permission. Separate from Cedar execution policy. |
| **Approval quorum** | The number of distinct currently eligible human approve votes required by one matching allow rule (one or two). Any one matching allow rule may satisfy it; votes are not pooled across incompatible rules. |

## Metering

| Term | Meaning |
|---|---|
| **UsageEvent** | Append-only metering record (`llm` or `tool` kind) flowing gateway → bounded Redis stream → Postgres, with tool counts delivered to Stripe meters. The reporting projection detects retained-stream gaps and pauses meter delivery; it is not an invoice-complete durable billing source. |

## Sandboxes and isolation

| Term | Meaning |
|---|---|
| **Conformance sandbox** | Target egress-denied deterministic fixture runner for connector contracts. Current fixture tests are offline by convention until the runner exists; neither proves a live vendor effect. |
| **Trusted worker isolation** | Container and pod fault and resource isolation for reviewed first-party connectors. It is not containment for malicious publisher code. |
| **Untrusted connector sandbox** | Deferred phase-2 WASM runtime for third-party connector packages, with no ambient capabilities and no credential bytes. Guests normalize plans and evidence but never authorize or verify. |

{/* TODO: docs/GLOSSARY.md carries two rows each for "Capability" and "Route decision record"; both pairs are merged above. Reconcile the source table so the duplication is removed at the origin. */}

<Columns cols={2}>
  <Card title="Invariants" icon="shield" href="/concepts/invariants">
    The rules this vocabulary was built to keep precise.
  </Card>
  <Card title="Evidence trust" icon="scale" href="/receipts/evidence">
    The full ladder, and what each class can conclude.
  </Card>
</Columns>