@gomission/trust-graduation

Reference wrapper for the Trust Graduation Protocol v0.1: action-class autonomy from observed evidence. Zero dependencies. Wraps any agent runtime.

Capability is commoditizing. Permission is not. Trust Graduation specifies how an agent earns the right to act for a principal — action class by action class, through evidence, with receipts, and revocation when behavior degrades.

This package is the canonical reference implementation. The protocol is open. Alternative implementations conforming to the v0.1 contract are welcome.

• Protocol spec: see PROTOCOL.md.
• Schemas: https://gomission.io/schemas/v1/trust-evidence.schema.json, https://gomission.io/schemas/v1/trust-posterior.schema.json.
• Wrapper: this package — drop-in for Claude API tool use, OpenAI function calling, LangChain, or raw loops.

Install

npm install @gomission/trust-graduation

Quick start

import { createTrustEngine, filesystemStorage } from "@gomission/trust-graduation";

const trust = createTrustEngine({
  storage: filesystemStorage({ dir: ".trust-graduation" }),
});

// Before any consequential tool call, gate it.
const decision = trust.gate("email.send.external");
if (decision.decision === "approval_required") {
  // Hold the action. Surface this to the principal. Do not proceed.
} else {
  // tier === "supervised" or "auto_capped" — proceed within the spec's limits.
}

// After the principal decides, record evidence so future calls graduate.
trust.recordEvidence({
  action_class: "email.send.external",
  label: "approved",
  date: "2026-06-12",
});

API

The 5-method contract from PROTOCOL.md §3:

• recordEvidence(row) — append one observed event for one action class.
• posterior(actionClass) — return Beta(α, β) posterior with mean, 95% CI, sample counts.
• tier(actionClass) — current enforcement state: gated | supervised | auto_capped | review.
• graduationReady(actionClass) — true when tier is past gated and not review.
• requiresReview(actionClass) — true when a trust violation has been recorded.

Plus a convenience helper:

• gate(actionClass) — { tier, decision: "permitted" | "approval_required", post }.

Canonical action classes

The spec recommends these as the v0.1 baseline. Implementations MAY add more.

| Action class | Type | | --- | --- | | draft.compose | Internal | | draft.response | Internal | | email.send.internal | Internal | | email.send.external | External — never auto-promotes past gated | | calendar.create | Internal | | social.post.public | External — never auto-promotes past gated |

External-effect classes are observational only. They never auto-graduate; the principal must approve each call. See PROTOCOL.md §2.5.

Canonical labels and weights (§4.2)

| Normalized label | Weight | Quality | | --- | ---: | --- | | sent | +1.00 | strong | | approved | +0.85 | strong | | minor_edit | +0.35 | partial | | edited | -0.15 | ambiguous | | heavy_rewrite | -0.55 | partial | | held | 0.00 | neutral | | rejected | -1.00 | strong | | dropped | -1.00 | strong |

Labels matching the trust-violation pattern (§6.1) carry weight -1 and force the action class into review until the principal clears it.

Storage

Two reference backends ship in-box:

• memoryStorage() — in-process, useful for tests.
• filesystemStorage({ dir }) — append-only JSONL on disk.

Implement your own by exposing { append(row), all(), forClass(actionClass) }.

Example: wrap any tool call

See examples/wrap-tool-call.mjs for a working demonstration of:

1. Gating an action class before calling a tool.
2. Recording evidence after the principal decides.
3. Watching the same class graduate from gated to supervised across rounds.
4. External-effect classes staying gated by spec, regardless of evidence.

Run it:

node examples/wrap-tool-call.mjs

Use with Claude Desktop

Pair this wrapper with @gomission/mcp. The MCP server surfaces the approval ceremony inside Claude conversations; this wrapper supplies the posterior math and evidence ledger that decide what to surface.

Posterior math

Implements PROTOCOL.md §5: Beta(2, 2) prior, label-weighted updates, 95% credible interval via bisection on the regularized incomplete beta (continued fraction). Adequate for typical evidence counts (<10⁴). For higher precision at scale, supply your own posterior backend that conforms to the same return shape.

License

Copyright (c) 2026 Phenomena Labs Ltd. Proprietary and confidential. See LICENSE.

The Trust Graduation Protocol itself is published as an open specification. Implementations conforming to PROTOCOL.md v0.1 are welcome regardless of license.