docs/GLOSSARY.md in the Obol repository; if a pull request introduces a new domain noun, it gets a row there.
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.
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. |
Invariants
The rules this vocabulary was built to keep precise.
Evidence trust
The full ladder, and what each class can conclude.