Skip to content
Browse the documentation
Workflow packs

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:

  • 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).

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.