Skip to main content

Glossary

This is the canonical vocabulary for Agent Vigilo documentation. Inline terms throughout the site open the same definitions and link back to their entries here.

Code identifiers and stored values appear in code style. For example, a run can have operational status = completed and policy gate_status = fail at the same time.

Runtime Roles​

Vigilo CLI
Command entry point for evaluator publishing, run management, shard administration, and runtime service modes.
A command can perform work directly or run a coordinator or worker process.
Coordinator
Process that advances durable creation recovery, lease recovery, dispatch, finalization, and outbox publication.
Many coordinators can run concurrently because database claims divide work.
Worker
Process that consumes chunk-ready broker messages, claims chunks, invokes the agent target and evaluators, and persists results.
Many workers can run concurrently; a chunk claim selects one current owner.
Bounded work
Work limited by a configured item count, concurrency count, time budget, or retry budget.
Prevents one cycle, placement, chunk, or evaluator from consuming unlimited resources.
Container
Independently runnable process or infrastructure service in a deployment view.
A container is a deployment boundary, not necessarily an operating-system container.
Command flow
Decisions and side effects produced by one CLI command.
One flow follows one command from input through persistence and external calls.

Evaluation And Results​

Agent target
HTTP service or workflow whose behavior is being evaluated. It may wrap a model, prompt pipeline, or multi-step agent.
One versioned target configuration per run profile.
Run profile
Versioned configuration for the agent target, evaluator bindings, scoring, persistence, retries, and gate behavior.
One profile snapshot per run; unrelated to a Cargo build profile.
Dataset
Versioned collection of evaluation cases.
One dataset version per run.
Case
One immutable input, optional expected output, and routing metadata from a dataset.
A case can be evaluated once in a run.
Input
Case data sent to the configured agent target.
One required input value per dataset case.
Expected output
Optional oracle data available to evaluators but not sent to the agent target.
Zero or one expected value per dataset case.
Task type
Case label used by automatic run-profile matching.
One task type per dataset case.
Tags
Case labels used by tags_any and tags_all profile matching rules.
Zero or more tags per dataset case.
Case group
Run-profile rule that selects evaluator bindings and aggregation policy for matching cases.
One explicit group or one or more automatically matched groups per case.
Evaluator
Versioned WASM component that examines an agent output and returns one measurement or abstention plus optional diagnostics.
Identified by <namespace>/<name>:<version>.
Evaluator binding
Stable profile entry that assigns an evaluator measurement to host-owned normalization, threshold, requiredness, dimension, weight, and blocking policy.
Identified by evaluators[].id; many bindings can apply to one case.
Evaluator identifier
Immutable published identity in <namespace>/<name>:<version> format.
One identifier selects one versioned evaluator artifact.
Measurement
The single raw observation returned by a completed evaluator invocation.
Binary, numeric, or ordinal; the profile explicitly maps it to utility and judgment.
Normalization policy
Profile-owned mapping from a raw evaluator measurement to a score between 0.0 and 1.0.
Binary, numeric linear, numeric curve, numeric threshold, or ordinal mapping; invalid values are rejected.
Evaluator outcome
Invocation execution state: completed, error, or abstained.
Separate from the host-derived passed or failed quality judgment.
Diagnostic finding
Non-authoritative evaluator observation with severity, category, reason, evidence, and tags.
Zero or more per invocation; diagnostics cannot score or block.
Evaluator completeness
Execution-level check that every required binding produced exactly one valid, normalized measurement.
Errors, abstentions, missing results, duplicates, or invalid measurements withhold authoritative scores.
Dimension
Profile-owned scoring bucket, such as format or quality.
Host-normalized binding results are grouped into dimensions before total scoring.
Dimension score
The min_score or weighted_mean result for one dimension of one execution.
Zero or one score per configured dimension and execution.
Aggregate score
Weighted total of an execution's dimension scores.
Zero or one total score per execution.
Run scorecard
Authoritative run-wide dimension and evaluator gate results merged from shard-local counters.
One immutable scorecard per completed run; includes coverage, score, error, abstention, and pass-rate metrics.
Blocking result
Host-derived failed binding result that can fail an execution independently of its aggregate score.
Blocking comes only from evaluator binding or dimension policy.
Execution
Durable evaluation of one dataset case against the agent target.
One expected execution per case in a run.
Attempt
One worker's effort to complete an execution. Retries create later attempts.
Many attempts can belong to one execution; only the current attempt is authoritative.
Current attempt
Attempt ID and number that an execution currently authorizes to write terminal state.
Zero or one authoritative attempt per execution.
Run
One durable evaluation of a dataset version with a run profile and agent target.
A run contains chunks and expected executions.
Run status
Operational lifecycle state such as creating, pending, running, completed, failed, or cancelled.
One current value per run.
Gate status
Policy outcome such as unknown, pass, or fail.
One current value per run; distinct from run status.

Work And Routing​

Chunk
Bounded range of dataset cases processed under one worker claim.
Many chunks per run; each chunk belongs to one run shard.
In-flight chunk
Chunk-ready broker delivery currently being processed by one worker process.
Bounded per worker process by max_inflight_chunks.
Prefetch
RabbitMQ limit on unacknowledged deliveries reserved by one consumer.
Configured per worker consumer.
Chunk parallelism
Number of case executions processed concurrently inside one claimed chunk.
Bounded independently from in-flight chunk count.
Run shard
Stable logical segment numbered 0..127 and stored as run_shard; it keeps a chunk and its execution-owned rows together.
A run uses only the shards assigned to its chunks.
Control database
PostgreSQL role that owns global run state, placement metadata, dispatch cursors, creation plans, and control outbox records.
Exactly one active control-capable database placement.
Execution database
PostgreSQL role that owns shard-local chunks, snapshots, executions, attempts, results, summaries, and chunk-ready outbox records.
One or more shard-capable placements; the control database may also serve this role.
Database alias
Stable name such as primary or shard_001 used instead of a connection URL.
One alias per database placement.
Database placement
Catalog entry that maps a database alias to a secret environment-variable name, role, and status.
One row per configured PostgreSQL target.
Database placement status
Admission lifecycle for a target: active accepts and serves ownership, draining serves existing ownership but accepts none, and disabled serves no runtime work.
One status per database placement.
Placement drain
Guarded transition that stops new shard ownership before routes are moved away and a database placement is disabled.
The drain does not move rows by itself.
Database router
Process-local DatabaseRouter that reads placement metadata and resolves control or execution pools.
One lazily initialized router per Vigilo process; it does not choose new shard assignments.
Database circuit breaker
Process-local admission guard that temporarily skips one unavailable database alias without changing durable routing.
One independent circuit per contacted execution database alias and process.
Shard placement
Control-plane mapping from run_id + run_shard to a database alias, lifecycle, route version, and write epoch.
One row per used run shard.
Execution route
Resolved shard placement plus the PostgreSQL pool for its current database alias.
Resolved for one run_id + run_shard.
Route version
Monotonically increasing control-plane CAS generation changed by every route alias or lifecycle update.
One current value per shard placement; not a schema or deployment version.
Write epoch
Monotonically increasing execution-ownership generation carried by routed work and validated in the destination database.
Changes only when ownership moves or is restored.
Local shard admission
Execution-database authority row containing the accepted write epoch and open, draining, prepared, or closed state.
One row per locally known run_id + run_shard; checked in the write transaction.
Dispatch cursor
Control-database progress for dispatching one run shard.
One cursor per used run shard after creation; drained forbids further dispatch.
Chunk dispatch window
Bounded set of pending chunks selected from one run shard in one dispatch operation.
One window can create one run.chunk.ready outbox event record per selected chunk.
Coordinator cycle
Ordered iteration of creation recovery, lease recovery, chunk dispatch, finalization, and outbox publication.
Repeats for coordinator start; runs once for coordinator once.
Coordinator pass
One bounded stage within a coordinator cycle, such as dispatch or outbox publication.
A pass can visit multiple database aliases.
Shard move
Targeted relocation of one run_id + run_shard route and its shard-owned rows to another database alias.
One run shard per move operation.
Rebalance plan
Persisted set of targeted shard moves for a capacity or placement-drain operation.
One plan contains many rebalance items.
Rebalance item
Claimable plan item for moving one specific run_id + run_shard.
One shard move per item; concurrent apply processes can claim different items.

Ownership And Concurrency​

State
Persisted lifecycle value used to determine which transitions are valid.
One current lifecycle value per stateful record.
Transition
Guarded database change from one state to another.
A transition applies only when its authority and current-state predicates hold.
Owner
Process or claim that currently has guarded authority to perform a state transition.
Ownership is temporary unless represented by durable placement state.
Claim
Successful transition that gives a process temporary authority over one work item.
Examples include chunk, dispatch-cursor, outbox-delivery, and rebalance-item claims.
Lease
Time-bounded claim authority that becomes recoverable after its deadline.
Expiry permits recovery but does not alone prevent a stale write.
Claim token
Opaque value issued with a claim and required to settle or renew that exact claim.
A newer claim gets a different token, fencing the previous owner.
Fencing token
Value whose equality proves that an owner or route is still current.
Checked on every protected mutation; claim tokens and route versions are fencing values.
Row lock
PostgreSQL lock on selected table rows, usually held until the transaction ends.
PostgreSQL enforces conflicting row-lock modes.
Admission lock
Transaction-scoped PostgreSQL advisory lock used cooperatively by shard writers.
Normal writers take the shared form; shard movement takes the exclusive form for one run_id + run_shard.
Route fence
Expected database alias, placement status, and route version validated immediately before a routed write.
One expected fence per resolved execution route.
Route CAS
Compare-and-swap update that changes a route only while its stored alias, lifecycle, and route version still match.
Serializes concurrent control-plane route changes.
Compare-and-swap
Update that succeeds only if stored values still equal expected values.
Used to change a route or settle a claim without overwriting newer state.
Idempotent operation
Operation that can be repeated without duplicating its logical effect.
Retries may execute more than once while producing one durable outcome.
No-op
Valid path that changes nothing because another process already advanced the state.
A no-op is a successful convergence outcome, not necessarily an error.
Recovery
Reassignment or repair after a lease expires or a durable workflow stops mid-operation.
Recovery preserves retry limits and invalidates stale owners.
Stale attempt
Attempt that is no longer authoritative because its lease expired, its chunk was recovered, or a later attempt superseded it.
Retained for history but rejected as a current writer.

Events And Messaging​

Outbox event record
Durable outbox_events row inserted in the same database transaction as the state change it describes.
One logical event per unique dedupe_key.
Outbox delivery row
Temporary publish work in outbox_delivery_queue.
One active delivery row per unpublished outbox event record.
Publish claim
Time-bounded ownership of an outbox delivery row, fenced by claim_token.
One current publisher claim per delivery row.
Broker
RabbitMQ transport that carries published messages from coordinators to workers.
Transport is at-least-once; durable authority remains in PostgreSQL.
Broker message
RabbitMQ message created from an outbox event record after publication.
May be delivered more than once.
Worker delivery
One broker delivery that identifies a chunk for a worker to claim.
A delivery is acknowledged, delayed, requeued, or quarantined after processing.
Event type
Semantic event name such as run.started, run.chunk.ready, or run.completed.
Stored on the outbox record and used for broker routing.
Dedupe key
Stable identity for one logical outbox event record, also published as the AMQP message ID.
Unique in the outbox ledger.
At-least-once delivery
Delivery guarantee that permits redelivery after uncertain acknowledgement.
Consumers must use database claims and idempotency guards.
Publisher confirm
RabbitMQ acknowledgement that a published message reached the broker.
Required before the outbox event record is marked published.
Message settlement
Worker acknowledgement, delayed redelivery, or requeue decision for one broker delivery.
One settlement outcome per received delivery.

Evaluator Packaging​

WIT
WebAssembly Interface Type definition used as the evaluator ABI source of truth.
Versioned contracts live under wit/evaluator/<version>/evaluator.wit and become immutable when released.
WIT world
WIT boundary that groups the evaluator's imported and exported interfaces.
The evaluator implements evaluator-world.
Evaluator ABI
Exact versioned WIT binary contract implemented by an evaluator WebAssembly component.
Identified by package, world, interface, version, and immutable contract hash.
Evaluator host adapter
Version-specific host binding that validates, invokes, and maps one supported evaluator ABI.
Selected from the run's immutable execution plan.
Evaluator execution plan
Hashed run snapshot of the exact evaluator ids, artifact hashes, ABI identities, adapters, runtime versions, and scoring policy hash.
Frozen once per run and verified by every worker placement.
WASI Preview 2
Component-oriented WASI target used by evaluator artifacts.
Rust target wasm32-wasip2.
Evaluator artifact
Compiled WebAssembly component stored in the evaluator registry.
One immutable artifact content per evaluator identifier.
Evaluator registry
Durable catalog of published evaluator identities, metadata, contracts, and artifact content.
Contains many versioned evaluators.
Package manifest
Cargo.toml file that supplies evaluator crate identity and version.
One Cargo manifest per evaluator crate.
Evaluator manifest
Vigilo.toml file describing artifact paths, WIT expectations, and publish metadata.
One per evaluator package.
WIT contract
Immutable versioned interface definition that a compiled evaluator component must implement.
Validated by declaration, contract hash, and typed component linking.
Build profile
Named artifact selection in Vigilo.toml, such as dev or release.
Selects a build output; not an evaluation run profile.
Wasm store
Fresh Wasmtime execution state created for one evaluator invocation.
One isolated store per invocation.
Fuel
Deterministic Wasmtime instruction budget for one evaluator invocation.
Exhaustion interrupts evaluator execution.
Evaluator semaphore
Process-local cap on concurrently active Wasm evaluator invocations.
One shared semaphore per worker process.
Publish
Validate and insert a versioned evaluator artifact into the evaluator registry.
Publishing is immutable for one evaluator identifier.

Cardinality At A Glance​

one run
  -> many chunks
  -> one expected execution per dataset case
  -> one or more used run shards
       -> one shard placement per used shard
       -> one dispatch cursor per used shard
       -> many chunk dispatch windows over time
            -> one run.chunk.ready outbox record per selected chunk

one run.started outbox record per run
one broker message per publish attempt, with possible redelivery

Multiple run shards can share one database alias. A coordinator pass can report counts for several aliases even though each routed operation targets one database at a time.