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 reference/user-glossary.md. The two files must not disagree.

Routing and requests

• Attempt — One entry in a request’s routing sequence. Shape: { endpoint, provider_key, source, fallback_index, auth_type, priority, 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, cost rank, optional Redis disallow-list filtering, and optional PTB attempts (when NEXUS_GATEWAY_PTB=1). It copies each provider key’s byok_only flag onto the attempt but does not branch on it; the flag is carried for the policy layer and is not consulted during routing. Implemented in services/gateway/src/routing/builder.rs.
• AttemptExecutor — Runs attempts in order against providers and owns the escrow reserve/commit/cancel lifecycle for PTB attempts. The retry-or-fail decision for one try, and the retry budget shared across every candidate in the request, live in services/gateway/src/retry.rs — see decisions/0026-shared-retry-budget-with-full-jitter-backoff.md. 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.
• Registry artifact — One signed JSON document holding the complete catalog and pricing for one provider lane: a catalog table (one row per model, with capabilities and aliases) and a rates table (one row per priced meter, with context bands and effective intervals), plus source evidence. The optional artifact name is the lane identity used by model strings, credentials, policy, billing, and telemetry; the typed provider selects the existing adapter backend. nexus-registry-artifact verifies the schema, references, pricing rules, the content SHA-256 digest, and optional Ed25519 signatures without database or network access; applying an artifact replaces its lane’s registry state (absence is reviewed retirement).
• Import change set — Persisted comparison of one validated registry artifact with a provider’s current Postgres baseline. Approval binds the artifact, baseline, provider revision, findings, schema, contract, generator, actor, and expiry; apply revalidates those values and commits under provider-scoped locking through nexus-registry.

Context and grouping

• 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.
• Reporting dimension — A workspace-defined string key assigned to an API key by a workspace manager. The gateway snapshots its value and assignment provenance into request analytics, so later API-key changes do not alter historical reports. Reporting dimensions are not request headers and do not affect classification or authorization.

Classification and access

• 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 ../vortex-common-crates/contracts/policy-obligations.md. 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.
• Personal developer key / developer access token — User-bound credential (nxd_…) issued by auth for non-browser Query/Trace HTTP access. Distinct from gateway API keys (nxs_…) and trace ingest keys. Console surface: Account → Personal developer keys. Details and examples: dev/personal-developer-keys.md.
• PDP (Policy Decision Point) — Evaluator that, given a PolicyQuery (subject, resource, action, context), returns a PolicyDecision (effect, obligations, reason_code) per ../vortex-common-crates/contracts/policy-obligations.md. 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. 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 ../vortex-common-crates/contracts/policy-obligations.md.

Telemetry and storage

• Tier 1 telemetry — Tenant-visible analytics stored in ClickHouse per ../vortex-common-crates/contracts/telemetry.md. 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 ../vortex-common-crates/contracts/audit-event.md. Use this word, never "immutable".

Audit and governance

• Audit Event — Canonical record shape defined in ../vortex-common-crates/contracts/audit-event.md. 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.

Cryptography

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

SDK surfaces

• 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.

Delivery methodology (repository-wide)

• 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.

Superseded or redirected terms

• “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.