Evidence provenance
The trust class every fact carries, which key class may push what, and why an agent's own report never satisfies a pack contract.
Last changed Markdown versionllms.txt
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:
independentwhere a native connector exists for the source (Stripe refunds and credit notes, Coinbase orders and fills, Shopify orders, helpdesk status by connector).sharedwhere 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 aseffect_below_trust, never silently satisfied. Since pack 2.3.0 each effect also statesmin_trust_class(backend_attestedon every refund effect), the class this page's model computes.- Nothing from
runtime_contextoragent_self_reportsatisfies 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_idas 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.