Explorer UI

The Verity Explorer is a web-based dashboard for observing and managing your protected effects in real-time. Think of it as the Stripe Dashboard for execution safety — every lease, commit, failure, and recovery is visible and actionable.

Dashboard

The main dashboard provides an at-a-glance view of your system's health:

Total effects — how many protected actions exist
Status breakdown — committed, running, failed, expired effects
Recent activity — timeline of recent lease/commit/fail events
Failure rate — percentage of effects that ended in failure

Effects List

The Effects page lists all protected effects with filtering and search:

Filter by status — RUNNING, COMMITTED, FAILED, EXPIRED
Filter by namespace — view effects in specific namespaces
Search by key — find effects by their effect key
Sort by time — most recent first

Effect Detail Drawer

Click any effect to open the detail drawer, which shows:

Status + timestamps — when the effect was created, leased, committed/failed
Effect key + name — the business-meaningful identifier
Fence token — current fence token value
Agent ID — which agent/worker processed this effect
Input data — the inputJson passed to protect()
Result / Error — the committed result or failure details
Workflow context — case ID, run ID, workflow name (if part of a workflow)

Audit Trail

Every effect has a full audit trail — a chronological record of every significant event:

Event Type	Description
`LEASE_GRANTED`	An agent acquired the lease (includes fence token, agent ID)
`LEASE_RENEWED`	Lease was extended (automatic background renewal)
`LEASE_EXPIRED`	Lease timed out without commit or fail
`OBSERVE_HIT`	observe() found a prior result (action already completed)
`OBSERVE_MISS`	observe() returned null (action needs to be executed)
`COMMITTED`	Action result recorded in ledger (includes source: observed/acted)
`FAILED`	Action failure recorded (includes error details)
`RESET`	Admin reset a failed effect for retry
`FORCE_COMMITTED`	Admin manually committed a result
`FORCE_FAILED`	Admin manually recorded a failure

Each event includes timestamps, fence tokens, IP addresses, and detailed JSON payloads. This creates a complete forensic record of what happened, when, and why.

Cases Page

When using workflows, the Cases page shows your workflow executions as a date-grouped timeline:

Running cases — show progress bar with completed/total effects
Completed cases — show completion time and run count
Failed cases — show inline error hints for quick triage
Run tracking — how many execution attempts each case took

Click a case to see all its effects and drill into individual effect details.

Namespaces Page

The Namespaces page lists all active namespaces with aggregate statistics:

Effect counts — total effects per namespace
Status breakdown — how many committed, running, failed
Freeze/unfreeze — admins can freeze a namespace to block all new lease acquisitions during incidents

Freezing a namespace is an incident response tool. When frozen, all protect() calls to that namespace will fail with 403. Existing leases continue until they expire. Use it when you need to stop all agent activity in a namespace while investigating an issue.

Admin Actions

The Explorer provides several administrative actions for org_admin users:

Reset Failed Effects

When an effect is in FAILED state, admins can reset it to allow retry. This:

Changes the effect state from FAILED back to a retryable state
Records a RESET event in the audit trail with the admin's reason
Sets priorState: 'reset' for the next lease acquisition
The next protect() call will skip observe() and go directly to act()

Force Commit / Force Fail

For effects stuck in RUNNING state (e.g., due to CommitUncertainError), admins can:

Force commit — manually record a result if you know the action succeeded
Force fail — manually record a failure if you know the action failed

Both actions are recorded in the audit trail with the admin's identifier and reason.

Use force actions carefully. They bypass the normal lease/fence token validation. Only use them when you have verified the actual state of the external system.

Environment Switching

The Explorer shows data for the environment matching your API key:

vt_test_ key → shows test environment data only
vt_live_ key → shows live environment data only

Data between environments is completely isolated. You will never see test effects when using a live key, and vice versa.

Access Control

Role	Capabilities
`agent`	Execute effects only (lease, commit, fail, renew). No Explorer access.
`org_admin`	Full Explorer access. View all effects, manage namespaces, reset effects, force actions, manage API keys.