Engineering Glossary

Contributor-facing nexus terminology. One authoritative definition per term. If you find yourself reaching for a term not on this page, add it here in the same MR.

End-user-facing definitions — deliberately friendlier, covering only the terms that appear in console copy or the public API — live in User Glossary. The two files must not disagree.

• Attempt — One entry in a request’s routing sequence. Shape: { endpoint, provider_key, auth_type, priority, source, byok_only, needs_escrow, escrow_budget_usd }. Every attempt has a human-readable source string (for example "openai/gpt-5.4-mini/byok") that surfaces in logs and traces. Pattern adopted from Helicone — see reference/helicone-lessons-learned.md. Implemented in services/gateway/src/routing/types.rs.
• AttemptBuilder — The component that enumerates every candidate attempt for a request, respecting BYOK-first ordering, per-provider byok_only flags, cost rank, optional Redis disallow-list filtering, and optional PTB shadow attempts (when NEXUS_GATEWAY_PTB=1). Implemented in services/gateway/src/routing/builder.rs.
• AttemptExecutor — Runs attempts in order against providers; owns the retry-or-fail decision for each single attempt and the escrow reserve/commit/cancel lifecycle for PTB attempts. Implemented in services/gateway/src/routing/executor.rs.
• Endpoint — A resolved (model, provider, deployment) triple with URL, pricing, feature flags, and request parameters. Endpoints are produced by the registry from ModelProviderConfig + per-deployment overrides.
• ModelProviderConfig — The registry template for a (model, provider) pair. Human-authored; becomes one or more Endpoint records when paired with deployment overrides.
• Model string grammar — "<model>", "provider/<model>", "nexus/auto", and comma-separated fallback routes are all parsed by nexus-registry::parse_model_route. Deployment suffixes are not part of the grammar.
• BYOK — Bring Your Own Key. The tenant supplies provider credentials; the provider bills the tenant directly. nexus routes the request using those keys and records usage locally but does not settle cost. Multi-provider fallback is supported.
• PTB — Pass-Through Billing. nexus supplies provider credentials; the tenant pays nexus, which pays the provider. Requires an escrow reservation on the hot path. Workspace wallet storage is Postgres-backed through the EscrowService trait in nexus-control-plane-core::wallet.
• Escrow — Pre-request worst-case cost reservation for PTB attempts. Workspace wallet, transaction, and escrow rows live in the control-plane migrations; StoreEscrow in nexus-control-plane-core::wallet drives gateway reserve/commit/cancel integration. See decisions/0016-postgres-escrow.md.

• Session — A logical grouping of multiple LLM requests associated with one agent run or one user-facing conversation. Identified by nexus-session-id, optionally shaped by nexus-session-path and nexus-session-name. The gateway reads the headers into the analytics envelope, ingest stores session_id on request rows, and query/console expose session lists, timelines, and live views.
• Trace / Span — A trace is a tree of spans sharing one trace identifier. Nexus uses OTLP spans for operator telemetry (Tier 2) and a separate tenant-visible agentic trace pipeline for SDK and application spans: trace-ingest accepts OTLP exports under project-scoped keys, records are normalized into Nexus-owned shapes, ingest materializes them into ClickHouse, and query/console expose trace trees. They are not audit events.
• Trace artifact — A large or sensitive payload associated with a trace span or event, such as span input, span output, tool arguments, tool results, retrieved document content, images, audio, or raw provider payload. Trace artifacts use the same opt-in and policy-governed capture stance as full request/response bodies.
• Payload state — The storage state for a trace payload: summary_only, full, omitted, or redacted.
• Trace ingest key — A project-scoped write-only credential for submitting external SDK or OTLP/OpenInference trace data. It is not valid for gateway model traffic, Query APIs, control-plane APIs, or audit reads.
• Property — A tenant-defined dimensional tag attached via nexus-property-<name>: <value> request headers. Not consumed by the shipped gateway handler.

• Classification — A data-sensitivity label attached to requests via the nexus-classification header contract. The vocabulary is per-scope: workspaces, orgs, and projects each store an ordered classification lattice (ClassificationLattice in vortex-classification, low to high), a default label, and a ceiling label, editable via the console, the REST classification PATCH endpoints, and nexus workspaces update / orgs update / projects update. Children may extend the parent lattice (parent labels stay an ordered subsequence; they cannot be removed or reordered) and may only tighten the ceiling; parent edits cascade downward. New workspaces seed the standard vocabulary public < internal < confidential < restricted; orgs and projects inherit their parent’s lattice, default, and ceiling at creation. The gateway validates the header against the governing scope’s lattice (unlabeled requests take the project/org default label; labels outside the vocabulary are rejected with 400), and the policy engine denies requests whose label outranks the scope’s classification ceiling, per the policy obligations contract. Labels a lattice does not define fail closed. Richer ABAC attribute sources are not implemented.
• Tenant — The identity, billing, and isolation root. Auth users and sessions are scoped to a tenant, and hosted deployments may resolve the active tenant from the request host or subdomain.
• Workspace — A grouping inside a tenant that owns organizations, workspace-level memberships, wallets (PTB balances, spend caps), and workspace-scoped audit views. Hierarchy: tenant → workspace → organization → project.
• Organization — A grouping inside a workspace. Organizations own projects, org-level settings, memberships, and policy defaults.
• Project — A workload scope inside an organization; the unit of API-key issuance, provider-key registration, usage attribution, and most RBAC/ABAC checks.
• Membership role — The per-org/project (and per-workspace) RBAC role on a membership: manager (full administration), auditor (user-level access plus read access to the audit log), or user (self-service member). Roles rank user < auditor < manager (Role::rank in vortex-auth-core); workspace manager/auditor memberships extend to the workspace’s organizations.
• Principal — The authenticated subject of a request (user, service account, or API-key-derived subject). Carries claims that populate PolicySubject on a PDP query.
• PDP (Policy Decision Point) — Evaluator that, given a PolicyQuery (subject, resource, action, context), returns a PolicyDecision (effect, obligations, reason_code) per the policy obligations contract. Callers apply obligations before performing the gated action; unknown obligation kinds are treated as deny. Lives in services/policy: the gateway evaluates gateway.request queries in-process against the shared engine or over gRPC, enforcing the classification ceiling and carrying redaction obligations. Requests without a nexus-classification header take the project (or org) default label.
• Obligation — A side-effect a PolicyDecision requires the gateway or ingest to perform. See the policy obligations contract.

• Tier 1 telemetry — Tenant-visible analytics stored in ClickHouse per the telemetry contract. The gateway publishes request.completed envelopes that ingest materialises into the requests table.
• Tier 2 telemetry — Operator-only system telemetry exported over OTLP through vortex-telemetry. Collector sidecars run in Compose; per-service OTLP metric depth varies relative to the full contract taxonomy.
• Envelope — The metadata-rich record the gateway emits per request for downstream analytics on nexus.requests.<org_id>.<request_id>. Bodies <= 256 KB are inline; larger bodies are chunked over NATS and reassembled by ingest.
• WORM — Write Once Read Many object-lock pattern for audit archives. The audit service writes archive objects tracked by worm_object_key, and the dev MinIO enables object locking; production Object Lock retention configuration is operator responsibility.
• Tamper-evident — The property of the audit log delivered by per-tenant Merkle chains and signed batch roots per the audit event contract. Use this word, never "immutable".

• Audit Event — Canonical record shape defined in the audit event contract. Distinct from a request log; do not conflate the two pipelines.
• Inclusion proof — Merkle path from an event leaf to a signed batch root. The nexus-audit-verify CLI verifies archives and emits proof bundles; the audit service serves proofs over gRPC and the /api/audit/events/:event_id/proof HTTP route, and the console audit viewer downloads them.
• Break-glass — Heavily gated workflow where approvers grant temporary elevated access with full auditing. Not implemented in-tree today.
• Legal hold — Retention override preventing TTL eviction. Not implemented in-tree today.

• KmsProvider — Trait for wrapping and unwrapping secret material (vortex-auth-core::kms). FileKms is the live implementation used by the CLI and gateway.

• Drop-in edge — A gateway surface an unmodified provider SDK can target by changing only its base URL and API key. Two ship: the OpenAI-compatible edge at /v1/... (ADR-0005) and the native Anthropic Messages edge at /anthropic/v1/... (ADR-0012, used via ANTHROPIC_BASE_URL). Client SDKs are the official OpenAI and Anthropic SDKs pointed at the gateway; there is no separate first-party client SDK.

• Thin vertical slices, skeleton-then-grow, and “no forward references in acceptance criteria” are defined in process/methodology.md. Use that file for process rules; do not restate them here when they change.

• “Immutable log” — not used by nexus. Use tamper-evident instead, and name the verifier (nexus-audit-verify).
• “Complexity classification” — not a nexus concept. Complexity-tier routing is a client-side helper (T1/T2/T3); classification is data sensitivity.
• “Request log” as a synonym for “audit log” — not equivalent. Request analytics rows are a different pipeline from tamper-evident audit records.