# Glossary (/docs/reference/glossary)



Definitions for the terms used throughout Ductor documentation.

## Clearing primitives [#clearing-primitives]

The public vocabulary of the clearing lifecycle — **priced → routed → executed →
settled → proven**. Each maps onto an internal type defined elsewhere in this
glossary; a page bridges to the API name on first use.

**Work** — a unit of value to be priced, routed, and done: a lead, a ticket, an
AI task, an inbound event. The API type is the
<TechnicalName public="Work" api="Routable" /> (see *Routing → Routable*).
Shipping.

**Worker** — anyone who can take Work: a human, a team, a queue, an external
system, or an AI agent, carrying capacity, capabilities, and a settlement
account. Pool **recipients** and agent definitions remain the substrate, and the
worker registry spans them as one identity with capacity, readiness, a pinned
agent definition, and a bid-eligibility check. Shipping.

**Bid** — a priced offer to do Work: a ping/post bid, a standing buy order, or an
Agent RFQ bid carrying ask price, SLA, and declared quality. Maps to market bids
(`ping_bids`, routing-market bids). The lead-market mechanisms ship today, as do
Agent RFQ bid terms, buyer-side clearing, and authenticated bid submission. What
is not yet built is the RFQ front door: publishing a task spec and having agents
bid on it autonomously.

**Route** — the decision binding Work to a Worker, with its explanation. The API
type is the <TechnicalName public="Route" api="Decision" /> plus its
`Explanation` (see *Routing → Decision*). Shipping.

**Receipt (Work Receipt)** — the immutable, signed evidence object joining a
Route's explanation, tool-manifest hashes, cost, consent trail, and settlement
reference for one cleared unit of Work. Ships as an opt-in surface: enable
issuance with an Ed25519 signing key, then read and verify receipts over the API
or the `work_receipt.verify` tool. Distinct from the internal MCP / tool-exposure
*Receipt* below, which is one component of the evidence it joins.

**Settlement** — the money movement closing out Work: charge, credit, fee, and
claw-back. Split across the pricing ledger, usage metering, and the Stripe
wallet; a balanced-entry settlement journal ships as an opt-in co-write, with
every posting forced to net to zero at commit.

**Warranty** — the review window in which settled Work can be returned if it
fails review, triggering a credit and an optional reroute. Implemented today as
the returns window (see *Billing & usage → Charge event*).

## Runtime [#runtime]

**Coordinator** — the serial, single writer of a workflow run's state row
(`eec_workflow_run`). Each wakeup, it loads state, applies pending attempt
results, computes the next tick, persists atomically with optimistic locking on
`record_version`, then dispatches newly-runnable steps.

**Step Worker** — one of many parallel workers that execute the actual units of
work (connector calls, rule evaluation, step logic). Workers never mutate run
state; they append outcomes as rows in `eec_workflow_step_attempt`, which the
Coordinator later folds in.

**Tick** — one Coordinator evaluation of a run: what's now runnable, what to
dispatch, what terminal state (if any) has been reached.

**Wakeup** — a signal that a run needs a Coordinator tick, delivered via Redis
`SyncMatch` or the tiered queue.

**Attempt** — a Step Worker's recorded outcome for a step, append-only.

**ContinueAsNew** — closing out an oversized run and starting a fresh one that
carries forward the state that matters, bounding history and run-state size.

**Scatter / gather** — fanning a step into many parallel branches and collecting
their results before proceeding.

**Optimistic locking** — the concurrency guard on run state: a commit is rejected
if `record_version` moved underneath it, and the wakeup is re-queued.

**Workflow definition** — a DAG of steps, edges, triggers, and checkpoints,
authored in YAML and keyed by a `family_slug`.

**Publish** — freezing an immutable version of a definition under its
`family_slug`; runs pin to the published version they started with.

## Routing [#routing]

**Routable** — the input to a routing decision — the thing being routed.

**Pool** — a named destination that holds recipients.

**Recipient** — a member of a pool that can receive a routable, with `weight`,
`capacity`, availability `state`, and other attributes.

**Rule** — a priority-ordered CEL expression that selects a pool (lower priority
number wins).

**Strategy** — a pluggable algorithm that selects a recipient *within* a chosen
pool. `Info()` is checked first for compatibility; `Select()` is the hot path.

**Routing pipeline** — the ordered stages every routable passes through:
Validate → Enrich → Filter → Select → Assign.

**RoutingContext** — the mutable carrier struct threaded through every pipeline
stage.

**Decision** — the output of routing: the selected recipient(s) plus metadata.

**Bundle** — a declarative YAML document of pools, recipients, rules, and
workflow refs, applied by the reconciler (GitOps).

**Pipeline mode** — how a pool/tenant routes: `linear`, `dag`, `shadow`, or
`inherit`.

## Connectors [#connectors]

**Provider** — a definition of a third-party system Ductor can talk to, keyed by
`providerKey`.

**Action** — an operation a provider exposes, keyed by `(providerKey,
actionKey)` in the Action Registry.

**Provider config** — a tenant's configuration of a provider.

**Connection** — a concrete authenticated link (an `AuthContext`) that a step
dispatches through; credentials are AEAD-encrypted at rest with
XChaCha20-Poly1305.

**Connect session** — the hosted OAuth flow used to establish a connection for
OAuth-based providers.

## Platform [#platform]

**Tenant** — the isolation boundary for data and quota; derived from the auth
token (JWT claims), optionally selected by an `X-Tenant-ID` header that must
match.

**Entitlement** — a tenant's plan/feature grants, enforced in `report`, `off`,
or `strict` mode.

**Idempotency record** — a Postgres `pending` → `completed` transition that makes
a retried mutating request safe to replay.

**AEAD** — Authenticated Encryption with Associated Data (XChaCha20-Poly1305),
used to encrypt connector credentials at rest.

**fx** — [Uber's fx](https://github.com/uber-go/fx) DI framework; the explicit
composition root that wires every layer in `cmd/ductor/fx_*.go`.

**sqlc** — the type-safe SQL codegen tool; all new queries go through it rather
than raw SQL.

**goose** — the database migration runner Ductor uses.

## AI & MCP [#ai--mcp]

**MCP** — Model Context Protocol. Ductor runs an **inbound** MCP server that
exposes its own tools to agents, and it **imports** tools from external MCP
servers (persisting discovered-tool snapshots and import receipts).

**Tool security descriptor** — per-tool security metadata that governs whether
and how an agent is allowed to call a given Ductor tool.

**Exposure manifest** — the resolved, tenant-scoped policy document declaring
which agent tools are exposed and under what constraints.

**Receipt (MCP / tool-exposure)** — a persisted, auditable record of an MCP
import/discovery run or a tool-exposure decision. This is one component of
evidence the public **Work Receipt** (see *Clearing primitives*) joins; the two
are not the same object.

**Agent session** — the stateful, Postgres-persisted context for a chat-agent
conversation across turns.

**Agent preset** — two related meanings: (1) one of Ductor's preset AI agents,
registered as a connector action so it appears in the workflow editor alongside
other connectors; and (2) a saved, reusable agent configuration bundle.

## Strategy (extended) [#strategy-extended]

**Eligibility trait** — a first-class recipient attribute evaluated by routing
*before* strategy selection, narrowing the candidate set.

**Feature snapshot** — an immutable capture of the strategy input features used
for a decision, persisted for replay and audit.

**Strategy state plane** — the persisted state layer strategies read from and
write to across decisions (as opposed to the stateless per-decision inputs).

**Shadow campaign** — a live counterfactual evidence plane that evaluates
candidate strategies against production traffic without affecting real outcomes.

**Strategy contract** — the interface a strategy implementation must satisfy;
a **strategy recipe** is a declarative, versioned strategy configuration.

**Strategy pipeline** — the ordered evaluation stages a strategy runs through
when producing a selection.

## Route DSL [#route-dsl]

**Route DSL v2** — the bounded public authoring language for routes; the
compiler lowers it into exact workflow-definition and route-generation
artifacts.

**RouteAggregate** — a top-level construct in the Route DSL v2 topology grouping
a route's pools, rules, and refs.

**RouteRecipe / RoutePack** — versioned DSL documents authored as mutable drafts
and published as immutable versions: a recipe describes one route, a pack bundles
several.

## Connectors & sync (extended) [#connectors--sync-extended]

**Sync variant** — a named variant of a bridge/connector sync operation.

**Sync run lease** — a lease that guarantees only one sync run is active for a
given target at a time.

**Credential health** — the tracked validity/health state of a connector
credential, used to surface and recover broken connections.

**Quota facts** — the resolved quota/entitlement facts consulted when admitting a
connector call.

**Execution admission** — the gate deciding whether a connector call may proceed;
a **fairness group** is the bucket it is fairness-scheduled within.

**Egress / placement decision** — the resolved outbound policy (egress) and the
target selection (placement) for a connector call, persisted as redacted policy
manifests and decision summaries.

**Integration deployment** — a first-class, persisted deployment of a connector
integration.

## Security & entitlements [#security--entitlements]

**KEK** — Key Encryption Key: the wrapping key (from a `key_provider` backend)
that protects the AEAD master key. See [BYOK config](/docs/reference/configuration).

**Crypto-shred** — irreversibly destroying a tenant's keys so its
encrypted-at-rest data becomes permanently unrecoverable.

**Custody mode** — how a tenant's encryption keys are held: platform-managed
versus operator-supplied (BYOK).

**Entitlement Source / Snapshot / Requirement / Surface** — the four entitlement
concepts. A **Source** feeds entitlement facts (e.g. billing); a **Snapshot** is
the resolved point-in-time set of facts for a tenant; a **Requirement** is what a
given action needs; a **Surface** is an enforced area of the product.

## Billing & usage [#billing--usage]

**Budget policy** — a tenant-scoped `warn` / `shadow_deny` / `deny` cap over a
windowed usage metric. See [Usage metering & budget policies](/docs/billing/usage-metering).

**Charge event** — a per-routing-decision charge record, carrying the triggering
`DecisionID`, settled via a durable effect intent. See
[Pricing, returns & compliance](/docs/billing/commerce).

**Usage metering** — durable tenant usage events recorded across a closed metric
catalog (e.g. `mcp.tool_calls`, `ai.requests`), each carrying a status
(`recorded` / `warned` / `shadow_denied` / `denied`). See
[Usage metering & budget policies](/docs/billing/usage-metering).

**Wallet** — a recipient-scoped prepaid balance held in the Stripe plugin,
denominated in cents. See [Stripe integration & invoicing](/docs/billing/stripe).

## Execution & bridge [#execution--bridge]

**Bridge** — the outbound sync/execution subsystem that calls external systems
over a hardened, SSRF-safe HTTP transport.

**Opcode** — a generator instruction emitted during bridge/DAG discovery that
describes one step of work to perform.

**Checkpoint** — a durable suspend/resume point in a run where control returns to
the Coordinator (e.g. awaiting an external callback).

**Inline run** — a workflow run executed inline for small payloads rather than
being externalized to object storage.

## Triggers & events [#triggers--events]

**Trigger plane** — the application boundary that accepts universal workflow
trigger **envelopes** from every external ingest source.

**Envelope** — the canonical typed wrapper carrying an event, trigger, or signal
payload plus its metadata.

**Wildcard event pattern** — an event subscription using `*` to match any event
rather than a single concrete event type.

**event\_set** — a workflow step that waits on a correlated *set* of events (keyed
by a CEL-derived correlation key) before proceeding.

**Digest** — a content hash of a payload used for correlation and deduplication.

## Storage & retention [#storage--retention]

**`eec_` prefix** — the shared prefix on Ductor's durable runtime tables
(`eec_workflow_run`, `eec_workflow_step_attempt`, `eec_task`, `eec_routing_idempotency`,
`eec_dlq`, …). It stands for *Enterprise Eventing Core*: the durable event, task,
workflow, dispatch, and DLQ foundation.

**Journal payload budget** — the per-payload byte, retention, and redaction
budget enforced on durable workflow-journal writes.

**Retention class / compaction** — each workflow transition carries a retention
class; the compaction policy drops compactable transitions to bound run history.

**Tiered fair queue** — the three-tier fair queue backing router work; items
live in **partitions** and are claimed under a **lease** with a visibility
timeout.

## Observability [#observability]

**K1 metric catalog** — the whitelist of Prometheus/VictoriaMetrics metrics the
analytics proxy accepts PromQL against; only catalogued metrics carrying a real
`tenant_id` label are queryable per tenant.