# Evidence provenance

A verdict is only worth what its evidence is worth. CommitLayer already keeps three layers of defence: connectors
are read-only and their facts carry the connection's trust; the facts API accepts a source only from a key bound
to it and never from a key for a source a live connector serves; and `min_trust` on an expected effect makes the
compiled SQL ignore facts below the bar. The packs make the provenance of every fact explicit and give contracts a
vocabulary for what may satisfy a check.

## What every fact carries

| Field | Today | With packs |
|---|---|---|
| `source_id` | `Fact.source` | unchanged |
| `source_type` | the connection's kind (`facts`, `both`, `internal`) | unchanged, exposed in views |
| `source_principal` | `Fact.connection_id` (connector or the per-tenant `agent_api` connection); the pushing key is in the audit log | the pushing key's id is kept on facts-API facts (`attributes._pushed_by` is not used; a column) |
| `subject_id` | `Fact.subject_id`, `subject_kind` | unchanged |
| `observed_at` | `Fact.occurred_at` | unchanged |
| `ingested_at` | `Fact.created_at` | unchanged |
| `watermark` | per connection, or per pushed source in `agent_api.config.watermarks` | unchanged |
| `raw_ref` | `Fact.raw_ref` (idempotency key and evidence pointer) | unchanged; packs store hashes and pointers, never bodies |
| `trust_class` | not stored; trust is the connection's | **new column** `facts.trust_class`, set at ingestion |

## Trust classes and how they are assigned

| trust_class | Assigned when | Maps onto the ladder |
|---|---|---|
| `native_connector` | a read-only connector wrote the fact | the connection's trust (`independent` by default) |
| `customer_backend` | the facts API, pushed by an evidence key (`facts:write` without `actions:record`) whose `evidence_class` is `customer_backend` (the default) | `backend_attested` once an Owner or Admin attests the source for that key (`POST /v1/evidence/attestations`); until then `agent_reported` (or `legacy_unattested` where the deprecated per-source rating still lifts it) |
| `provider_webhook` | the facts API, pushed by an evidence key with `evidence_class: provider_webhook` (the provider's relay, not the customer's code) | the source's declared trust |
| `blockchain_confirmation` | the facts API, pushed by an evidence key with `evidence_class: blockchain_confirmation` (an indexer or node reader) | the source's declared trust |
| `imported_batch` | CSV / XLSX / Parquet upload | the connection's trust (`shared` by default) |
| `runtime_context` | OpenTelemetry ingestion (`agent.action.*` spans), the x402 adapter's own observations | **capped at `self_reported`** |
| `agent_self_report` | the facts API, pushed by a key that also holds `actions:record` (the same principal recorded the action) | **capped at `self_reported`** |

The cap is the enforcement. `min_trust` already ranks facts by `COALESCE(config.source_trust[source],
connection.trust)`; with packs the rank is `MIN(that, class_ceiling(trust_class))`, so a fact classed
`agent_self_report` or `runtime_context` never satisfies an effect that asks for `shared` or `independent`, whatever
an operator declared for the source. Nothing else changes for existing customers: facts without a class (rows
written before the column existed) rank as before, and the backfill that classifies them runs after boot in the
deferred migration lane.

Tool-returned responses are not facts at all. The recorder records the intent (parameters of the call); the
response, success message included, is carried as context on the action (`params.mcp_tool`, `mcp_request_id`) and
is never written as a fact. A pack contract therefore cannot be satisfied by "the tool said OK".

## What a pack contract asks for

Every authoritative expected effect names a `min_trust`:

- `independent` where a native connector exists for the source (Stripe refunds and credit notes, Coinbase orders
  and fills, Shopify orders, helpdesk status by connector).
- `shared` where the customer's own system is the system of record (an internal order system, a provider's
  delivery ledger, a resource server's log) and an Owner or Admin has attested the pushed source for the evidence
  key that sends it. Until they do, the record is received but not eligible, reported as `effect_below_trust`,
  never silently satisfied. Since pack 2.3.0 each effect also states `min_trust_class` (`backend_attested` on
  every refund effect), the class this page's model computes.
- Nothing from `runtime_context` or `agent_self_report` satisfies an outcome check. They may add context: the
  pack's views show them beside the authoritative facts and the x402 adapter's observations help an investigator
  correlate, but the verdict does not depend on them.

The six kinds of evidence the brief names map as follows: direct evidence = `native_connector` or
`blockchain_confirmation`; derived evidence = `imported_batch` and connector-derived state facts; connector
evidence = `native_connector`; customer-backend evidence = `customer_backend`; runtime self-report =
`runtime_context`; tool-returned responses = not evidence.

## Credentials

| Credential | Scopes | Holds | Cannot |
|---|---|---|---|
| Runtime recorder | `actions:record`, `actions:read` (preset `recorder`) | record intent, read verdicts | push facts, change contracts |
| Evidence ingestion | `facts:write`, `actions:read`, `connectors:read` (preset `evidence`), bound to named `fact_sources`, with an `evidence_class` | push facts and watermarks for its sources | record actions, push a source a connector serves, change contracts |
| Operator | a signed-in analyst | save drafts, select (activate) contracts, install packs, push records by hand | attest a source or change any trust; the records a person pushes carry no credential, so they are classed `agent_reported` (`no_credential`) and are never `backend_attested` |
| Governance | a signed-in Owner or Admin | attest or revoke an evidence source for one evidence key (one confirmation, audited and versioned), create keys, change plan; the legacy per-source rating (deprecated) | attest with an API key: neither the recorder nor the evidence key can attest, and no key can raise its own trust |

A key that holds both `actions:record` and `facts:write` is allowed to exist for backwards compatibility, but every
fact it pushes is classed `agent_self_report` and capped. MCP principals never hold `facts:write`
(`MODEL_FACING_SCOPES`) and no MCP tool selects a contract; the pack tools add nothing that writes. One remaining
gap is filed rather than hidden: a full-scope API key carries the analyst role and could call
`POST /v1/contracts/{id}/select` (board CL-74 notes it; the fix is a scope `contracts:activate` that model-facing
and runtime keys never receive).

## Identity links

Links are `SubjectLink` rows: `left_source`, `left_subject_id`, `right_source`, `right_subject_id`, `link_type`,
`method` (`exact_id`, `external_id`, `hashed_email`, `hashed_phone`, `time_window`), `confidence`, tenant-scoped,
with `created_at`. Packs add no table; they add rules in the manifest (which link types a workflow needs) and a
coverage check (are links of that type arriving). Provenance is the `method` plus the connection or key that wrote
the link; the compiler already restricts effect matching to the action's subject and its linked subjects, so an
unrelated subject can never satisfy another's contract. The pack-specific link vocabularies are:

- Stripe Customer Operations: `stripe_customer` ↔ `internal_customer`, `payment` ↔ `order`, `refund` ↔ `payment`,
  `order` ↔ `helpdesk_ticket`, `crm_contact` ↔ `internal_customer`.
- x402 Service Delivery: `payment_request` (payment-requirements hash) ↔ `tx_hash`, ↔ `payer_wallet`, ↔
  `resource`, ↔ `mcp_tool_call`, ↔ `delivery_record`, ↔ `customer_request_id`.
- Coinbase Agent Trade: `action_id` ↔ `client_order_id` ↔ `coinbase_order_id` ↔ `fill_id`; `agent_id`, `portfolio_id`,
  `strategy_id` as attributes on the action and the order facts.

## What a pack never stores

Private keys, seed phrases, raw signing credentials, unencrypted payment secrets, full sensitive response bodies.
The x402 pack stores the payment-requirements hash, the transaction hash, the response digest and evidence pointers;
the Stripe pack stores Stripe object ids and amounts; the Coinbase pack stores order and fill ids, products, sizes
and prices. Customer identifiers continue to be keyed hashes at ingestion, as today.
