Local Evidence And The Run Ledger

Purpose: explain what Actspan records locally, how commands read that evidence, and when portal reporting changes the operating model.

Start Here

Complete one local run, then list the saved attempts from the same workspace directory:

actspan runs --limit 10

Copy a run ID from the result. Use actspan inspect RUN_ID, replacing RUN_ID with that value. Expected: inspection identifies the target and status, plus available steps, provider, model, policy and evaluation bindings, metrics, and artifact references. Do not edit files under .actspan/; those files are generated evidence and command state.

For a complete allowed → gateway-denied → locally blocked → restored demo, follow the LiteLLM gateway guide.

Distinguish A Policy Block From A Provider Failure

The gateway failure and the local policy block are separate enforcement decisions. A provider failure is not evidence that Actspan blocked the request before dispatch. runs may display the stored status success or error where inspect displays succeeded or failed; both retain blocked for admission denials.

New execution records retain the target name and kind, elapsed milliseconds, and reported numeric token counts, including zero. Provider error responses and exceptions are saved as failures with their reason; inspection shows the saved error code when available. Credential fields remain redacted. Earlier records are not rewritten, and token counts already masked in historical records cannot be recovered by inspection. Rerun the workflow to collect fresh evidence.

Native CLI admission denials receive a run ID and a saved decision with detailed policy violations. In the LiteLLM demo, removing gpt-4.1-mini from the local model allowlist produces a MODEL_NOT_ALLOWED violation even though the gateway key permits that model. Restoring the policy allows the next attempt; it does not alter the saved block.

Interpret The Revisions And Metrics

The configuration fingerprint includes the authored local file referenced by gateways.<name>.config_file. It excludes live gateway settings, remote MCP data, plugin implementation, and resolved environment values. A local file hash does not prove the running gateway loaded that file or uses those settings. See gateway configuration files. If the fingerprinted configuration changes during admission, the revision status is changed_during_admission; if fingerprinting fails, it is unavailable. Neither case assigns a configuration revision to the blocked decision.

Latency on a blocked attempt measures local processing and admission checks, not model response time. Cost and tokens shown as - mean no value was recorded; they do not mean a measured zero. A native admission block leaves provider cost and usage unset because the provider did not execute. Numeric zero values, when recorded, remain distinct from missing values. Costs can come from configured pricing estimates and should not be treated as provider billing receipts.

Find A Specific Attempt

actspan runs displays one row per run ID, consolidating available evidence before applying --limit. The append-only ledger and its audit hashes remain unchanged. Listings use the latest supplied cost snapshot, including an explicit unknown cost, so earlier placeholder costs cannot override final pricing. actspan inspect RUN_ID selects that recorded attempt. Inspection by target name, such as actspan inspect summarize_agent, selects its latest saved attempt. After restoring a policy and running again, the name resolves to the new success. Use the blocked attempt's run ID to inspect the earlier denial.

Check Whether Evidence Was Saved

--no-state disables saving the blocked attempt. If local persistence is disabled or fails, the command still blocks execution and explicitly reports the evidence as disabled or unavailable; the generated run ID alone does not prove it was saved. A successful local write is accompanied by its ledger receipt.

Default Local Model

The Actspan CLI is self-contained by default:

actspan run
  -> execute locally
  -> append local Run Ledger evidence
  -> store large artifacts separately
  -> no external database required

Local CLI evidence storage needs no separate Postgres, ClickHouse, Temporal, OpenTelemetry or SQLite service. The refund application separately uses a local SQLite business ledger through Python's standard-library driver. Model requests still use the configured provider or gateway endpoint.

Run Ledger

The workspace-local source of execution history is:

.actspan/state/runs.jsonl

The ledger is append-only JSONL. New run records can include:

• ledger schema version and timestamp
• run ID, target kind, target name, workflow, and status
• provider and model metadata available to the runtime
• step outcomes, latency, token usage, and cost
• policy and execution-contract context
• output and artifact references
• audit-chain fields

Large outputs and generated files should remain in artifact storage and be referenced from the ledger rather than embedded repeatedly.

Read Local Evidence Through The CLI

Use supported commands instead of manually parsing .actspan/ files:

actspan runs
actspan inspect RUN_ID
actspan compare BASELINE_RUN_ID CANDIDATE_RUN_ID
actspan artifacts list RUN_ID

Replace the uppercase run ID labels with IDs from actspan runs before running these commands.

The CLI returns an empty local history when no Run Ledger exists. It does not silently substitute a legacy SQLite run database.

State And Lockfile Are Different

.actspan.lock.yaml
  resolved workspace and dependency identity

.actspan/state/runs.jsonl
  evidence from what executed locally

The lockfile supports reproducible setup and drift review. It is not run history. The Run Ledger records execution evidence. It is not the approved dependency lock.

Review lockfile drift with:

actspan lock --check
actspan lock --diff

Regenerate only after reviewing the workspace or dependency change:

actspan lock
actspan lock --diff

Optional Portal Reporting

Portal reporting adds shared, tenant-scoped visibility without replacing local evidence:

CLI or SDK
  -> write local evidence first
  -> upload to the portal when configured
  -> retain failed delivery in the local outbox

Runtime intent is explicit:

Connect and inspect configuration with:

actspan portal connect
actspan portal status
actspan portal sync

See enable portal reporting later to switch a locally initialized workspace to connected reporting.

Portal downtime should not destroy a successful best-effort local execution. Use the outbox and portal sync to retry eligible evidence delivery.

Enterprise System Of Record

Local files are appropriate for one developer or one CI workspace. The portal is the shared system for organization, workspace, project, access-control, audit-search, evaluation, approval, retention, and reporting workflows.

The intended boundary is:

CLI only
  -> local .actspan files

CLI + portal
  -> local evidence
  -> optional shared upload

Portal
  -> tenant-scoped operational and analytics stores

Related Documentation

• Quickstart
• Execution status
• How Actspan works
• Portal client guide
• Self-hosted deployment

Local evidence trust boundary

“Append-only” describes how the CLI writes the ledger, not protection against the account that owns it. That user or a process with the same filesystem rights can alter or delete local evidence and recompute unauthenticated hashes. A content hash detects a change only against a separately trusted reference; it is not an authenticated attestation of what happened.

Retain original evidence with your organization's access controls and backups. For shared revision checks, use revision evidence packages and compare the manifest hash with the retained portal copy. These package hashes still do not prove a client reported truthful results. No independent external anchor or immutable storage is established by the default local setup. Review product data handling before uploading.