Zephr Docs

Trust

Trust makes a belief's standing a first-class, enforceable property rather than a rendering hint. It owns the review state machine, the provenance chain, the verification ladder, tamper evidence, and the gating that other capabilities consume — every capability consumes trust state, and none of them may set it. The admission-scope and Firewall walkthrough lives in Concepts: Trust; this page covers the capability itself. Externally verifiable attestations are designed, not shipped (see Status honesty).

Availability

SurfaceTierResidencyNotes
zephr_verify (MCP)searchdeferredVersion-chain integrity, provenance anchors, review state
zephr_rules (MCP)reviewdeferredTrust Firewall policy per worktree
zephr_status (MCP)coreresidentRuntime state and service health
zephr verify, verify-claim, preflight (CLI)——T1 + T2 verification and plan-time advisory checks

Review state machine

Every belief carries exactly one review state — UNREVIEWED (the default), CONFIRMED, STALE, DISPUTED, or REJECTED. The field is non-null from the moment a candidate becomes a belief and is never collapsed into a numeric score:

  • Agents can never self-confirm. Confirmation is scoped (scope is not transitive upward) and records who, when, and against what.
  • Automated transitions are restricted to demotion. Code drift, reviewer departure, and contradiction demote rather than resolve; a demoted belief keeps its content and history. Drift- and expiry-demotion paths are keyed on attestation records, which no live production path produces yet (see Status honesty).
  • Rejection is tombstoned and blocks relapse. A rejected claim cannot quietly return as a new belief.
  • DISPUTED beliefs are disclosed with their dispute, never suppressed.

Core-eligible recall states are confirmed + valid; the Firewall can only narrow that set, never broaden it.

Verification ladder

Three tiers with declared limits: T1 deterministic checks assert only mechanical facts (structure, chain integrity); T2 semantic contrast checks against confirmed memory only; T3 budgeted judgment (rate-limited, self-untrusted) is specified but not shipped — today zephr_verify runs T1 + T2. It returns a verificationProfile plus warnings and reports verified only for well-formed, provenanced, confirmed beliefs — only well-formed chain (current-version pointer, contiguous revisions, non-overlapping transaction intervals, one open version) passes. Escalation to T3 and the human handoff at budget exhaustion are design, not a shipped path.

Status honesty

Shipped and registry-visible: the review-state field and its transitions, the Trust Firewall (zephr_rules), verification (zephr_verify, CLI verify), provenance disclosure (zephr_why), and recall gating. Specified in the trust spec but not shipped today: signed human attestation (keyless OIDC binding, offline-verifiable bundles, SLSA source-review slot), one-click renewal, hash-chained revisions, and Merkle-batched tamper proofs. No live confirm path produces an attestation record — design without assuming one exists behind a confirmation.

Persistence, security, observability

Review state and provenance persist alongside the belief base — attestation records do not, because none are produced on a live confirm path today (storage topology in Architecture; local data not encrypted by Zephr at rest). Provenance is content-addressed and lazily deep — it spans observation to usage, survives consolidation and revision, and is assigned by a deterministic classifier (Concepts: Provenance). Observability: the why-card states the reason for the current state inline; zephr_verify returns its verification profile and warnings. Tamper evidence is structural today (chain integrity checks); hash-chained revisions and Merkle-batched proofs are specified, not built (see Status honesty).

Limits and failures

  • No code path can create a belief in any state other than UNREVIEWED.
  • Gating thresholds are configured per scope and are not lowerable from below.
  • High numeric confidence never substitutes for a categorical review state — UNREVIEWED is disclosed verbatim.
  • A hand-tampered or edited artifact fails verification; signature mismatch surfaces as a trust-level error (see Continuity for the packet-resume variant).
  • Demotion is recoverable by the normal human review flow, not by rewriting state — trust state is never hand-set.

For verification failures and review-flow symptoms, see Troubleshooting.