> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manthan.systems/llms.txt
> Use this file to discover all available pages before exploring further.

# What is an Attestation

> The ExecutionAttestation schema every field, what it means, and what it proves

## Definition

An `ExecutionAttestation` is a cryptographically signed record of an authority verification outcome. It contains everything needed to independently verify that:

* A specific policy governed the decision
* Specific signals were evaluated
* A specific runtime version produced the outcome
* None of the above was modified after signing

The attestation is the proof. Not the log entry, not the database record the signed JSON object returned by `POST /execute`.

***

## Full schema

```typescript theme={null}
interface ExecutionAttestation {
  // Identity
  executionId: string;
  execution_fingerprint: string;

  // Policy
  policyId: string;
  policyVersion: string;
  schemaVersion: string;

  // Runtime
  runtimeVersion: string;
  runtimeHash: string;

  // Decision
  decision: {
    action: string;               // "approve" | "reject" | custom
    requires_override: boolean;
    reason: string;
  };
  execution_state: "completed" | "pending_override";

  // Hashes
  signalsHash: string;
  bundleHash: string;
  manifestHash: string;
  releaseManifestHash: string;
  evaluatorHash: string;           // deprecated alias for evaluatorSemanticHash
  evaluatorSemanticHash: string;
  evaluatorArtifactHash: string;

  // Trust
  manifestSignature: string;
  trustRootVersion: string;
  signerKeyId: string;

  // Signature
  signature: string;               // Ed25519 over canonical payload
}
```

***

## Field-by-field reference

### Identity fields

**`executionId`** Your business transaction identifier. You provide this in the execute request. Used as the replay protection key.

**`execution_fingerprint`** A SHA-256 hash computed by the runtime over the canonical form of `{ policyId, policyVersion, signals }`. This is the semantic identity of the decision independent of which business transaction triggered it. Two executions with different `executionId` values but identical policy and signals will have the same `execution_fingerprint`.

### Policy fields

**`policyId`** The identifier of the policy that governed this decision.

**`policyVersion`** The version of the policy bundle. Combined with `policyId`, this uniquely identifies the exact rule set applied.

**`schemaVersion`** The schema version of the policy format. Used during verification to confirm compatibility.

### Runtime fields

**`runtimeVersion`** The semver version of the governance server that produced the decision.

**`runtimeHash`** The content hash of the runtime binary. Together with `runtimeVersion`, this uniquely identifies the exact code that ran the evaluation.

### Decision fields

**`decision.action`** The outcome: `"approve"`, `"reject"`, or a custom action string defined in the policy (e.g., `"manual_review"`, `"hold"`, `"clinical_review"`).

**`decision.requires_override`** Whether human override is required before the authorized action can proceed.

**`decision.reason`** The human-readable reason string from the matched policy rule.

**`execution_state`** `"completed"` when the decision is final and the action may proceed. `"pending_override"` when the execution is blocked pending override resolution.

### Hash fields

**`signalsHash`** SHA-256 of the canonical signals. Equal to `execution_fingerprint` in current implementations.

**`bundleHash`** Content hash of the entire policy bundle. Proves exactly which policy content governed the decision.

**`manifestHash`** SHA-256 of the bundle manifest JSON.

**`releaseManifestHash`** SHA-256 of the release manifest — the file that records the runtime's own provenance.

**`evaluatorSemanticHash`** Hash of the policy evaluator's logic semantics. Two runtimes with the same semantic hash will produce the same decisions for the same inputs.

**`evaluatorArtifactHash`** Hash of the evaluator binary artifact.

**`evaluatorHash`** Deprecated alias for `evaluatorSemanticHash`. Present for backward compatibility.

### Trust fields

**`manifestSignature`** The Ed25519 signature over the bundle manifest, produced at compile time by the bundle signing key.

**`trustRootVersion`** The version of the trust root that anchors the signing key.

**`signerKeyId`** The key ID of the Ed25519 signing key that signed this attestation.

### Signature field

**`signature`** The Ed25519 signature over the canonical form of the attestation payload. This is the root of trust for the entire record.

***

## The signing chain

```mermaid theme={null}
flowchart TD
    TrustRoot["Trust Root\n(root.pub + trust-root.json)"]
    BundleKey["Bundle Signing Key\n(signerKeyId)"]
    PolicyBundle["Policy Bundle\n(bundleHash + manifestHash)"]
    BundleSignature["Bundle Manifest Signature\n(manifestSignature)"]
    RuntimeKey["Runtime Signing Key"]
    Attestation["ExecutionAttestation\n(signature)"]

    TrustRoot --> BundleKey
    BundleKey --> BundleSignature
    BundleSignature --> PolicyBundle
    RuntimeKey --> Attestation
    PolicyBundle --> Attestation
```

Verification confirms:

1. The `signature` is valid over the canonical attestation payload using the public key
2. The `bundleHash` matches the policy bundle content
3. The `manifestSignature` was produced by a key trusted by the trust root
4. The `runtimeVersion` and `runtimeHash` match the verifying runtime

***

## Storage

Attestations are plain JSON. Store the complete attestation object alongside your business record. Do not strip fields all fields are part of the signed payload and are needed for verification.

```typescript theme={null}
await db.decisions.insert({
  businessId: claim.id,
  attestation: JSON.stringify(attestation),
  governedAt: new Date(),
});
```

***

## Troubleshooting

**Attestation verification fails after storing** Ensure you are storing and retrieving the complete JSON object without modification. Do not re-serialize with a different key ordering — the canonical serialization in the signature covers the original byte sequence.

**`signerKeyId` does not match your public key** The attestation was signed by a different key than the one you are using for verification. Ensure you are using the public key that matches the `signerKeyId` value.

***

<Cards>
  <Card title="Runtime Verification" href="/verification/runtime">
    Verify a runtime's identity and integrity
  </Card>

  <Card title="Bundle Verification" href="/verification/bundle">
    Verify a policy bundle against the trust root
  </Card>

  <Card title="Independent Verification" href="/verification/independent">
    Verify offline with only the attestation and public key
  </Card>
</Cards>