How Vesanor Works
This page explains the core concepts behind Vesanor. Read this before diving into the technical docs — it gives you the mental model that makes everything else click.
The product loop
The primary Vesanor workflow is:
- Capture runtime behavior through
replay() - Review the workspace draft in Governance Studio
- Approve the current runtime artifact
- Enforce by environment at runtime
- Operate with Runs and References
That is the main product story. You do not need to hand-author local YAML packs to use it.
Fingerprints
Every test result gets a fingerprint — an 8-character hash that uniquely identifies the outcome. Same input + same output = same fingerprint.
Why this matters:
- Regression detection — if a fingerprint changes, the model's behavior changed
- Deduplication — identical failures across runs produce the same fingerprint, so you count unique issues instead of total noise
- Trend tracking — the dashboard shows fingerprint history so you can see when issues appear and disappear
Fingerprints are computed on redacted data (after SecurityGate removes any secrets), so they're safe to display and compare.
The capture-review-approve-enforce loop
This is the current Studio-first workflow:
1. Capture
Run your agent through replay() with an API key so Vesanor can build the current governance view for that workspace.
2. Review
Open Governance Studio and review:
- the workspace draft
- open judgments
- impact preview
- approval preview
3. Approve
Approve the workspace so Vesanor freezes the current runtime artifact for that environment.
4. Enforce
After approval, replay() applies environment-based runtime behavior from the approved artifact.
5. Operate
Use the operational surfaces to inspect what changed:
- Runs
- References / baselines
- conformance and drift findings
Baselines and drift detection
A baseline (reference) is your known-good standard. It's built automatically from successful runs.
The lifecycle
CANDIDATE → ACTIVE → STALE → RETIRED
- CANDIDATE — a new configuration starts collecting runs. After 7 successful runs with the same configuration in a 10-day window, it auto-promotes.
- ACTIVE — the trusted reference. Every new run is compared against it. Regressions are flagged and can block merges.
- STALE — drift detected (the model's behavior shifted since the baseline was established). Comparisons become advisory.
- RETIRED — superseded by a newer baseline.
Baseline key
Each unique combination of six fields produces a distinct baseline:
| Field | What changes it |
|---|---|
| Contract hash | You update your contracts |
| Provider | You switch from OpenAI to Anthropic |
| Model ID | You upgrade from gpt-4o-mini to gpt-4o |
| Runner version | Vesanor ships an update |
| Environment hash | Your environment changes |
| Normalization profile | You change response normalization settings |
Change any of these and a new CANDIDATE starts. The old baseline stays in its current state.
Failure classification
When a contract fails, Vesanor classifies why:
| Classification | What happened |
|---|---|
tool_not_invoked | Model returned text instead of calling a tool |
wrong_tool | Model called a different tool than expected |
schema_violation | Arguments don't match the expected schema |
malformed_arguments | Tool arguments aren't valid JSON |
path_not_found | An assertion path doesn't exist in the response |
unexpected_error | Provider returned an error |
Each failure also gets a fingerprint. If the same failure recurs across runs, the fingerprint stays the same — making it easy to track recurring vs. new issues.
Runtime workflow governance with replay()
replay() catches violations at runtime before the tool executes.
The enforcement pipeline runs on every LLM call:
- Narrow — remove tools the model shouldn't see in the current workflow phase
- Pre-check — enforce session limits (cost, call count, loops)
- Validate — check invariants, preconditions, forbidden tools, phase transitions
- Gate — block or strip illegal tool calls from the response
- Finalize — update session state, advance phase, record evidence
Protection levels
| Level | What it does | When to use |
|---|---|---|
| Monitor | Observes and captures, no blocking | Initial rollout, building confidence |
| Protect | Enforces contracts locally, blocks violations | Production agents without server dependency |
| Govern | Adds durable server-backed state and stronger evidence on wrapped paths | Shared sessions, approvals, stricter operational controls |
For the primary public path, start with zero-config governance and Governance Studio.
Provider abstraction
Vesanor normalizes provider differences so the runtime model stays consistent across supported providers.
The dashboard
The primary browser entry is Governance Studio. /dashboard redirects to /dashboard/studio, where you review workspaces, judgments, impact previews, approvals, and conformance findings.
The rest of the dashboard at app.vesanor.com provides secondary operational surfaces:
| Surface | What it shows |
|---|---|
| Governance Studio | Workspace list, Atlas/Control/Focus workbench, judgments, impact preview, approval, conformance |
| Contracts | Structured contract state already present in the tenant model |
| Guard | Validation coverage — how many tool calls are being checked and what's failing |
| Changes | Semantic diffs — what changed across contracts, runs, and baselines |
| References | Baseline lifecycle — trust posture, promotion status, drift alerts |
| Runs | Full run history with filtering, search, and drilldown |
Next steps
Now that you understand the concepts: