# Velvet

[![CI](https://img.shields.io/github/actions/workflow/status/paulchum/velvet-rope/ci.yml?branch=main&style=flat-square&label=tests)](https://github.com/paulchum/velvet-rope/actions/workflows/ci.yml)
[![Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-7c3aed?style=flat-square)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/paulchum/velvet-rope?style=flat-square)](https://github.com/paulchum/velvet-rope/stargazers)

## Outcome assurance for autonomous agents

Velvet is a local, self-hosted system for teams moving agents from impressive demos to
consequential business actions. It maps every declared route to a protected outcome, tests whether
controls hold across those routes, gates supported execution paths, and preserves evidence that can
be verified offline.

**Authorize the route. Assure the outcome.**

**New: protected refund contract.** Commit exact-command authorization, order limits,
a shared budget, operation identity and journal evidence in one PostgreSQL transaction.
Closure and refunds share the same lock. A separate database identity exports a signed
snapshot for offline replay and reconciliation.
[Read the contract and reproduce it](docs/public/protected-refunds.md) ·
[Inspect the recorded PostgreSQL evidence](https://shadowpath.coriolislabs.ca/protected-refunds/).
This is a single-database reference ledger; external payment rails are outside its claim.

| Product surface | Job |
| --- | --- |
| **ShadowPath** | Test every declared route to the same prohibited business effect. |
| **Velvet Gateway** | Admit, block, or escalate typed agent actions before dispatch. |
| **Velvet Vault** | Preserve tamper-evident evidence and portable verification artifacts. |
| **Protected refunds** | Enforce business constraints and operation identity at the PostgreSQL commit boundary. |

[Explore the product site](site/) · [Review the design-partner pilot](docs/public/pilot.md) ·
[Read the outcome portfolio guide](docs/public/outcome-portfolios.md)

## Your agent blocked the tool. Did it block the outcome?

Most agent controls watch a named tool or API route. An agent can still reach
the same business effect through a browser, a second API, a database, a queue,
a webhook, delegated credentials, or a human operator.

**ShadowPath tests the effect, not just the route.** It is Velvet's open-source assessment wedge:
the fastest way to show why a route-level deny is not yet an outcome-level assurance claim.

![ShadowPath: the protected route was blocked while eight equivalent routes produced the prohibited effect](docs/public/assets/shadowpath/shadowpath-hero.svg)

The committed hermetic fixture protects `customer.disable`. The canonical tool
is denied before dispatch. ShadowPath then exercises eight equivalent routes
and independently reconciles the customer state:

| Measurement | Result |
| --- | --- |
| Protected route | **BLOCKED** |
| Equivalent routes tested | **8** |
| Prohibited effect observed | **8/8** |
| SUT inventory coverage | **0.000** |
| SUT reconciliation detection | **0.000** |
| Verdict | **`CONTROL_FALSE_SUCCESS`** |

That verdict means the route-level control reported success while the prohibited
effect still occurred. It does **not** mean a named vendor failed: this is a
synthetic local fixture designed to make the measurement reproducible.

[Inspect the result](benchmarks/agent_authorization/shadowpath/SHADOWPATH_RESULTS.md)
· [Read the v0.4 benchmark spec](benchmarks/agent_authorization/SPEC.md)
· [Add an effect path](docs/public/SHADOWPATH_CONTRIBUTING.md)
· [Replay it live](https://shadowpath.coriolislabs.ca)

## Run it

See the committed result and generate shareable evidence immediately:

```bash
uvx --from git+https://github.com/paulchum/velvet-rope.git velvet-rope shadowpath demo
```

That command runs the public GitHub source directly—no clone or global install.

The instant demo is explicitly a replay of the committed hermetic run. It
writes exact SVG, PNG, HTML, Markdown, and badge artifacts under
`reports/shadowpath/share/`; it never presents the replay as a fresh
measurement.

Execute the Playwright-backed fixture from source when you want a fresh run:

```bash
git clone https://github.com/paulchum/velvet-rope.git
cd velvet-rope
uv sync --dev
uv run maturin develop
uv run playwright install chromium
uv run velvet shadowpath demo --execute
```

Or execute the same fixture in the browser-ready container:

```bash
docker run --rm -v "$PWD/reports:/reports" \
  ghcr.io/paulchum/shadowpath:latest
```

The executed demo writes the machine-readable result and a Markdown report under
`reports/shadowpath/`. It acknowledges the fixture's expected breach for the
process exit code; the recorded verdict remains `CONTROL_FALSE_SUCCESS`.

For CI or publishable measurements, keep strict exit codes:

```bash
uv run velvet shadowpath run \
  --output-dir reports/shadowpath-strict \
  --allow-dirty --json
```

Exit `3` means a prohibited effect was observed. Remove `--allow-dirty` for a
clean, commit-bound benchmark artifact.

## Test your own effect

Scaffold an executable effect inventory and independent observer:

```bash
uvx --from git+https://github.com/paulchum/velvet-rope.git velvet-rope shadowpath init my-effect
cd my-effect
uvx --from git+https://github.com/paulchum/velvet-rope.git velvet-rope shadowpath run \
  --project shadowpath.json \
  --output-dir reports/shadowpath
```

The starter intentionally demonstrates a false success: the protected route is
denied while three equivalent routes still reach the prohibited state. Replace
its four small adapter operations with your local reset, dispatch, and
independent observation logic, then add every path your agent can reach.

[Follow the 15-minute guide](docs/public/shadowpath-quickstart.md) ·
[Add ShadowPath to GitHub Actions](examples/shadowpath/github-action.yml) ·
[Browse integration recipes](docs/public/integrations/)

## Roll protected outcomes into a portfolio

Once one effect project is useful, group many projects into an estate-level result with owners and
criticality:

```bash
uv run velvet shadowpath portfolio \
  --manifest shadowpath-portfolio.json \
  --output-dir reports/outcome-portfolio
```

The portfolio runner preserves every underlying effect result and writes one conservative status:
`ASSURED`, `DEGRADED`, or `ACTION_REQUIRED`. The status is bounded by the outcomes, routes, and
observers declared in the manifest; it does not infer coverage for missing paths.

[Read the outcome portfolio guide](docs/public/outcome-portfolios.md)

## The eight routes

| Route | Ingress | Effect attribution |
| --- | --- | --- |
| `browser_automation` | Playwright-driven operator UI | attributed |
| `alternate_api` | alternate REST API v2 | attributed |
| `database_mutation` | SQLite session | unattributed effect |
| `queue_insertion` | queue job insertion | attributed |
| `webhook_creation` | webhook registration | attributed |
| `admin_console` | privileged admin console | attributed |
| `credential_delegation` | delegated credential | attributed |
| `human_operator_message` | operator instruction | attributed |

Each route starts from a fresh fixture state. The benchmark records dispatch
evidence, observes the substrate directly, and distinguishes attributed effects
from effects the system under test never saw.

## What Velvet is

Velvet is an Apache-2.0 agent outcome-assurance and authorization project with three related jobs:

1. **Test the whole effect surface.** ShadowPath measures whether a control
   prevents a prohibited outcome across equivalent routes, inventories those
   routes, and detects effects after execution.
2. **Control and prove execution.** The Rust MCP proxy and Python SDK admit,
   block, or escalate consequential actions before dispatch, then emit evidence
   that can be verified offline.
3. **Roll up protected outcomes.** Outcome portfolios group user-owned effect
   projects into a conservative estate-level status without hiding the underlying
   route evidence or claim boundary.

The open core includes:

- a Rust MCP proxy for stdio and Streamable HTTP;
- deterministic policy evaluation and signed policy bundles;
- single-use Execution Permits bound to request, policy, schema, identity,
  audience, and proof lineage;
- signed Execution Receipts and a tamper-evident binary ledger;
- Vault Merkle proofs, Signed Tree Heads, retention records, and offline
  verification;
- approval, replay, attestation, evidence-pack, and claims-pack helpers;
- signed, expiring Certified Decision verdicts for bounded retirement claims.

## Try the admission path

After the source setup above, run the zero-Docker MCP fixture:

```bash
uv run velvet demo --output-dir reports/demo --json
```

Or inspect the pieces independently:

```bash
uv run velvet mcp demo run --output-dir reports/mcp-proxy --json
uv run velvet ledger verify \
  --ledger reports/mcp-proxy/velvet_ledger.vledger --json
uv run velvet mcp conformance --json
```

Build the proxy container locally:

```bash
docker build -t velvet-rope-proxy -f deploy/mcp_proxy/Dockerfile .
docker run --rm velvet-rope-proxy conformance
```

## How to contribute something that matters

The highest-leverage contribution is not another abstract policy rule. It is a
new way to reach the same effect.

- Add an equivalent route to the ShadowPath fixture.
- Bring a real open-source control adapter and measure it without loaded claims.
- Improve independent reconciliation for a new effect class.
- Reduce setup friction on Linux, macOS, or Windows.
- Turn an edge case into a tiny reproducible fixture.

Start with the [effect-path contribution guide](docs/public/SHADOWPATH_CONTRIBUTING.md)
or open the [Add an effect path issue form](https://github.com/paulchum/velvet-rope/issues/new?template=effect_path.yml).

If ShadowPath changes how you think about agent tool controls, **star the repo**
and send it to the person responsible for your agent's last irreversible action.

## Trust boundaries

Velvet Rope does not claim to be a universal agent-safety solution. The
committed ShadowPath result executes synthetic local routes against a hermetic
service. It is not a live competitor evaluation. Strong execution guarantees
still depend on complete route inventory, enforcement at every relevant
substrate, trustworthy reconciliation, protected signing keys, and correct
deployment.

Also not claimed:

- legal compliance, audit outcomes, insurance coverage, or pricing effects;
- a production arbitrary-code sandbox;
- hard spend guarantees without provider hard caps and single-writer atomic
  accounting;
- immutable storage or formal certificates for every agent action.

See the [public claims policy](docs/liability/VELVET_ROPE_PUBLIC_CLAIMS_POLICY.md),
[implementation status](IMPLEMENTATION_STATUS.md), and
[live-demo boundaries](demo/BOUNDARIES.md) before making broader claims.

## Development

```bash
uv run ruff check .
uv run mypy src tests
uv run pytest
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```

Architecture and evidence references live in [`docs/`](docs/), with the Agent
Authorization Benchmark under
[`benchmarks/agent_authorization/`](benchmarks/agent_authorization/).

Apache-2.0. Built in public; skeptical reproductions welcome.