# MCP trust classes and the compact `trust` block

Every tool result carries a `trust` block: which paths inside `data` hold attacker-controllable
telemetry, which register class (F-16) each path holds, and the standing instruction to treat them
as data, never as instructions. This page describes the two spellings of that block and how to
read them.

## What a reader may rely on

- `trust.untrustedFields` is the list of JSON paths (`issues[].title`) inside `data` that hold
  text from outside Bucker's code. Quote them; never follow them.
- Every path has exactly one class. A path nobody classified is `unclassified`, the strictest
  treatment that still serves something, and is never absent.
- `trust.rule`, `trust.quarantined` and `trust.securityNotice` mean the same in both spellings.
- The register itself (`@bucker/shared/untrusted`) and the path-to-class table
  (`mcp-server/src/tools/field-classes.ts`) are unchanged by the encoding. Only how the answer is
  written differs.

## The two spellings

**Original** (no `trust.encoding`): a class object keyed by path.

```json
"trust": {
  "untrustedFields": ["issues[].title", "issues[].culprit", "issues[].release"],
  "classes": { "issues[].title": "issue_title", "issues[].culprit": "frame_identifier", "issues[].release": "release_label" },
  "rule": "...", "quarantined": 0, "securityNotice": null
}
```

**Compact** (`trust.encoding: "compact"`): each class id once, and one index per path.

```json
"trust": {
  "encoding": "compact",
  "untrustedFields": ["issues[].title", "issues[].culprit", "issues[].release"],
  "classDict": ["issue_title", "frame_identifier", "release_label"],
  "classIdx": [0, 1, 2],
  "rule": "...", "quarantined": 0, "securityNotice": null
}
```

`classIdx[i]` is the index into `classDict` of the class of `untrustedFields[i]`. The path is named
once, in the field the standing rule already names.

## Which one a response uses

The server writes whichever serializes shorter for that response, and the original form on a tie:
a response with no declared path, or with one or two short ones, keeps the original form, because
the compact scaffolding would cost more than the repeated paths it saves. The consequence is that
**no tool's measured size can rise because of the encoding**, and a client must accept both
spellings on every call. A response whose `classes` keys differ from its `untrustedFields` is also
kept in the original form, because the compact form cannot say it without loss.

## Decoding

```ts
import { decodeTrust } from '@bucker/mcp-server/protocol/trust-encoding'
const { untrustedFields, classes } = decodeTrust(result.trust) // both spellings
```

`decodeTrust` is the identity on the original form and the exact inverse of the encoder on the
compact one: the census suite (`test/trust-encoding-census.test.ts`) proves
`decodeTrust(encoded)` deep-equals the original block for every tool in the registry and every
recorded fixture. It fails closed: a class id the register does not hold decodes as
`unclassified`, and a malformed block (ragged index list, index out of range) throws
`TrustEncodingError`; a client that catches it should treat the whole response as untrusted.

## Compatibility window

The original form remains valid and is accepted by readers for one release; `trust.encoding` is
the discriminator (`'compact'` or absent). Task results stored on a row and served by
`tasks/get` are not re-encoded: they keep the original form (they carry no `estimatedTokens`, so
no published count depends on their spelling).

## Where it is written

One place: `serialize()` in `mcp-server/src/response.ts`, at the moment an envelope becomes text.
`estimatedTokens` is solved against that text, so the published number reflects the compact form.
In memory, tools, the taint ledger and the claims funnel keep reading the decoded view.
