> ## 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.

# Runtime Verification

> Verify the identity and integrity of a running Parmana runtime

## What runtime verification checks

Every attestation contains `runtimeVersion` and `runtimeHash` — the identity of the runtime that produced the decision. Runtime verification confirms:

1. The runtime's self-reported version and hash match the release manifest
2. The release manifest is signed by a trusted key
3. The runtime capabilities are compatible with the attestation's schema version

***

## Using verifyRuntime from @parmanasystems/core

```typescript theme={null}
import {
  verifyRuntime,
  LocalVerifier,
} from "@parmanasystems/core";
import fs from "node:fs";

const publicKey = fs.readFileSync("trust/root.pub", "utf8");
const verifier  = new LocalVerifier(publicKey);

const manifest = JSON.parse(
  fs.readFileSync("artifacts/release-manifest.json", "utf8")
);

const result = verifyRuntime(manifest, verifier);

console.log(result.valid);        // true
console.log(result.runtimeHash);  // "sha256:..."
console.log(result.version);      // "1.0.0"
```

***

## Using verifyRuntimeCompatibility

Checks that a runtime manifest is compatible with a given set of schema requirements:

```typescript theme={null}
import { verifyRuntimeCompatibility } from "@parmanasystems/core";

const result = verifyRuntimeCompatibility(manifest, {
  supportedRuntimeVersions: ["1.0.0"],
  supportedSchemaVersions:  ["1.0.0"],
});

console.log(result.compatible); // true
```

***

## Via the REST API

The `/runtime/manifest` endpoint returns the running runtime's manifest:

```bash theme={null}
curl http://localhost:3000/runtime/manifest | jq .
```

```json theme={null}
{
  "version": "1.0.0",
  "runtimeHash": "sha256:c9d4e5f...",
  "capabilities": ["execute", "verify", "audit"],
  "supportedSchemaVersions": ["1.0.0"],
  "startedAt": "2024-01-15T10:00:00.000Z"
}
```

Cross-reference the `runtimeHash` in this response with the `runtimeHash` embedded in attestations produced by this runtime. They must match.

***

## Checking an attestation against the runtime

When you receive an attestation, verify that its `runtimeVersion` and `runtimeHash` match a runtime you trust:

```typescript theme={null}
const attestation = await client.execute({ ... });
const manifest    = await client.runtimeManifest();

if (attestation.runtimeHash !== manifest.runtimeHash) {
  throw new Error(
    "Attestation runtimeHash does not match the current runtime. " +
    "The attestation may have been produced by a different runtime version."
  );
}
```

***

## Expected result

A successful `verifyRuntime` call returns:

```typescript theme={null}
{
  valid: true,
  runtimeHash: "sha256:c9d4e5f...",
  version: "1.0.0"
}
```

A failed call returns `valid: false` with a reason indicating which check failed.

***

## Troubleshooting

**`verifyRuntime` returns `valid: false`** — The release manifest signature does not verify against the public key, or the manifest has been tampered with. Do not trust attestations from this runtime until the issue is resolved.

**`runtimeHash` in attestation differs from `/runtime/manifest`** — The attestation was produced by a different runtime version than the one currently running. This is expected when the runtime is updated. For historical attestation verification, use the `runtimeHash` from the attestation itself — not the current runtime's hash. Verify the historical runtime's hash against the release manifest from that version.

**`verifyRuntimeCompatibility` returns `compatible: false`** — The runtime version or schema version does not appear in the `supported*` lists. The attestation may have been produced by a newer or older runtime than the one performing verification.