@cygnuxlabs/tracekit 1.3.0 → 1.4.0

package/README.md

@@ -1,5 +1,9 @@
 # @cygnuxlabs/tracekit
 
+> **Experimental:** the client and its Vercel AI SDK integration work and are tested, but may change and get less
+> hardening than the [stable core](https://github.com/Cygnux-Labs/Tracekit/wiki/Support). Its verifier
+> (`src/verify/`) is stable.
+
 Tracekit for TypeScript and JavaScript agents: every tool call is decided by the Tracekit signer before it runs and
 recorded after, and model responses become signed evidence. The client talks to the signer directly; it needs no Python
 at runtime (the same-user dev signer is started with Python when none is running).
@@ -14,7 +18,7 @@ npm install @cygnuxlabs/tracekit
 
 npm also installs the signer package for your platform (`@cygnuxlabs/tracekit-signer-<platform>`: Apple Silicon
 macOS, Linux x64 and arm64 with glibc, Windows x64), which bundles a Python, so `npx @cygnuxlabs/tracekit up` starts a
-dev signer without one. On an Intel Mac or Alpine there is none: `pip install 'tracekit-ai[signer]'`.
+dev signer without one. On an Intel Mac or Alpine there is none: `pip install tracekit-ai`.
 
 Or build it from a checkout and install the file it makes:
 
@@ -91,6 +95,14 @@ It does not check SLH-DSA checkpoint lines, Rekor anchors or certified record ke
 `UNVERIFIABLE (not checked by this verifier: ...)`, never `VERIFIED`. Monitor reports, revocations and the v1 format
 bridge need the Python verifier.
 
+`verify(bundle, null)`, with no trust config, runs every check that needs no pinned key and is never `VERIFIED`: a
+changed record still fails, an intact bundle is `UNVERIFIABLE (no trust config: ...)`.
+
+In a browser: `dist/verify.html` in this package (and a release asset) is this verifier as one self-contained page.
+Drop in a bundle and its trust config; its Content Security Policy lets it load and send nothing, so neither file
+leaves the browser ([verify in your browser](../../docs/verdicts.md#verify-in-your-browser)). `make verify-page` builds
+it from a checkout.
+
 ## v2 framework adapters
 
 One call registers a run (the dev signer is started if none answers), closes it when the process is about to exit,

package/bin/tracekit.mjs

@@ -15,16 +15,18 @@ if (args[0] === "verify" && args.includes("--trust") && !args.some((a) => PYTHON
     process.exit(2);
   }
   const { main } = await import("../dist/verify/cli.js");
-  process.exit(await main(args.slice(1)));
-}
-const cmd = signerCommand();
-if (!cmd) {
-  console.error(`tracekit: ${INSTALL_HINT}`);
-  process.exit(1);
-}
-const r = spawnSync(cmd[0], [...cmd.slice(1), ...args], { stdio: "inherit", env: signerEnv(cmd) });
-if (r.error) {
-  console.error(`tracekit: ${cmd[0]}: ${r.error.message}`);
-  process.exit(1);
+  // not process.exit(): it would cut off a report still being written to a pipe (past 64 KiB)
+  process.exitCode = await main(args.slice(1));
+} else {
+  const cmd = signerCommand();
+  if (!cmd) {
+    console.error(`tracekit: ${INSTALL_HINT}`);
+    process.exit(1);
+  }
+  const r = spawnSync(cmd[0], [...cmd.slice(1), ...args], { stdio: "inherit", env: signerEnv(cmd) });
+  if (r.error) {
+    console.error(`tracekit: ${cmd[0]}: ${r.error.message}`);
+    process.exit(1);
+  }
+  process.exit(r.status ?? 1);
 }
-process.exit(r.status ?? 1);

package/dist/v2/launcher.js

@@ -6,7 +6,7 @@
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { delimiter, dirname, join } from "node:path";
-export const INSTALL_HINT = "no Tracekit signer found. Install one: `pip install 'tracekit-ai[signer]'` (puts `tracekit` " +
+export const INSTALL_HINT = "no Tracekit signer found. Install one: `pip install tracekit-ai` (puts `tracekit` " +
     "on PATH), or reinstall @cygnuxlabs/tracekit without --omit=optional so npm adds the signer package for this platform";
 /** This platform's signer package suffix, as the optionalDependencies name them; null where none is built. */
 export function platformKey() {

package/dist/v2/rpc_schema.d.ts

@@ -1,3 +1,3 @@
 import type { Schema } from "./validate.js";
-export declare const RPC_VERSION = 17;
+export declare const RPC_VERSION = 19;
 export declare const REQUESTS: Record<string, Schema>;

package/dist/v2/rpc_schema.js

@@ -1,11 +1,11 @@
-export const RPC_VERSION = 17;
+export const RPC_VERSION = 19;
 export const REQUESTS = {
-    "register_run": { "type": "object", "additionalProperties": false, "required": ["request_id", "agent"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "tenant": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "principal": { "type": "string", "maxLength": 256 }, "principal_token": { "type": "string", "maxLength": 16384 }, "source": { "const": "migrated" }, "analyzes": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "replay_of": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "investigation": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "parent": { "type": "object", "additionalProperties": false, "required": ["run_id", "run_token"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 } } }, "agent": { "type": "object", "additionalProperties": false, "required": ["name"], "properties": { "name": { "type": "string", "maxLength": 128, "minLength": 1 }, "version": { "type": "string", "maxLength": 64 } } } } },
+    "register_run": { "type": "object", "additionalProperties": false, "required": ["request_id", "agent"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "tenant": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "principal": { "type": "string", "maxLength": 256 }, "principal_token": { "type": "string", "maxLength": 16384 }, "source": { "const": "migrated" }, "analyzes": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "replay_of": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "investigation": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "parent": { "type": "object", "additionalProperties": false, "required": ["run_id", "run_token"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 } } }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "agent": { "type": "object", "additionalProperties": false, "required": ["name"], "properties": { "name": { "type": "string", "maxLength": 128, "minLength": 1 }, "version": { "type": "string", "maxLength": 64 } } } } },
     "decide": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "stream", "client_seq", "tool_call_id", "tool", "args_source", "args"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "stream": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "client_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "tool_call_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "attempt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tool": { "type": "string", "maxLength": 256, "minLength": 1 }, "tool_class_hint": { "type": "string", "maxLength": 64 }, "args_source": { "enum": ["raw", "parsed", "coerced"] }, "args": {} }, "if": { "properties": { "args_source": { "const": "raw" } } }, "then": { "properties": { "args": { "type": "string", "maxLength": 1048576 } } } },
     "complete": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "stream", "client_seq", "tool_call_id", "decision_id", "args_digest", "status"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "stream": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "client_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "tool_call_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "attempt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "decision_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "args_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "status": { "enum": ["ok", "error"] }, "result": {}, "error": { "type": "string", "maxLength": 4096 }, "redacted": { "const": true }, "redaction": { "type": "object", "additionalProperties": false, "required": [], "properties": { "rules": { "type": "array", "maxItems": 32, "items": { "type": "string", "maxLength": 64 } }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } },
     "observe": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "stream", "client_seq", "source", "trust", "value"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "stream": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "client_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "source": { "type": "string", "maxLength": 256, "minLength": 1 }, "trust": { "enum": ["trusted", "untrusted"] }, "value": {} } },
     "state_write": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "stream", "client_seq", "key", "value_digest"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "stream": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "client_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "key": { "type": "string", "maxLength": 256, "minLength": 1 }, "value_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "prev_digest": { "oneOf": [{ "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, { "type": "null" }] } } },
-    "model_event": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "stream", "client_seq", "provider", "model", "phase"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "stream": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "client_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "provider": { "type": "string", "maxLength": 64 }, "model": { "type": "string", "maxLength": 128 }, "phase": { "enum": ["request", "response"] }, "content_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "exchange_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "streamed": { "type": "boolean" }, "stop_reason": { "type": "string", "maxLength": 100 }, "error": { "type": "string", "maxLength": 1024 }, "usage": { "type": "object", "additionalProperties": false, "required": [], "properties": { "input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "output_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cache_read_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cache_write_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reasoning_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "tool_uses": { "type": "array", "maxItems": 128, "items": { "type": "object", "additionalProperties": false, "required": ["id", "name", "executed_by"], "properties": { "id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "name": { "type": "string", "maxLength": 256, "minLength": 1 }, "executed_by": { "enum": ["client", "provider"] }, "args_source": { "enum": ["raw", "parsed", "coerced"] }, "args_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "args_unparseable": { "const": true }, "id_synthetic": { "const": true } }, "oneOf": [{ "additionalProperties": false, "properties": { "id": {}, "name": {}, "executed_by": { "const": "provider" }, "id_synthetic": {} } }, { "required": ["args_source", "args_digest"], "additionalProperties": false, "properties": { "id": {}, "name": {}, "executed_by": { "const": "provider" }, "id_synthetic": {}, "args_source": {}, "args_digest": {} } }, { "required": ["args_source", "args_digest"], "properties": { "executed_by": { "const": "client" } } }, { "required": ["args_source", "args_unparseable"], "properties": { "executed_by": { "const": "client" } } }] } }, "tool_results_sent": { "type": "array", "maxItems": 1024, "items": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" } }, "tool_results": { "type": "array", "maxItems": 1024, "items": { "type": "object", "additionalProperties": false, "required": ["id", "forms"], "properties": { "id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "forms": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "object", "additionalProperties": false, "required": ["digest", "result_digest"], "properties": { "digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "result_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" } } } } } } }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "body": {} } },
+    "model_event": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "stream", "client_seq", "provider", "model", "phase"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "stream": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "client_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "provider": { "type": "string", "maxLength": 64 }, "model": { "type": "string", "maxLength": 128 }, "phase": { "enum": ["request", "response"] }, "content_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "exchange_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "streamed": { "type": "boolean" }, "stop_reason": { "type": "string", "maxLength": 100 }, "error": { "type": "string", "maxLength": 1024 }, "usage": { "type": "object", "additionalProperties": false, "required": [], "properties": { "input_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "output_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cache_read_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "cache_write_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reasoning_tokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } }, "tool_uses": { "type": "array", "maxItems": 128, "items": { "type": "object", "additionalProperties": false, "required": ["id", "name", "executed_by"], "properties": { "id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "name": { "type": "string", "maxLength": 256, "minLength": 1 }, "executed_by": { "enum": ["client", "provider"] }, "args_source": { "enum": ["raw", "parsed", "coerced"] }, "args_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "args_unparseable": { "const": true }, "id_synthetic": { "const": true } }, "oneOf": [{ "additionalProperties": false, "properties": { "id": {}, "name": {}, "executed_by": { "const": "provider" }, "id_synthetic": {} } }, { "required": ["args_source", "args_digest"], "additionalProperties": false, "properties": { "id": {}, "name": {}, "executed_by": { "const": "provider" }, "id_synthetic": {}, "args_source": {}, "args_digest": {} } }, { "required": ["args_source", "args_digest"], "properties": { "executed_by": { "const": "client" } } }, { "required": ["args_source", "args_unparseable"], "properties": { "executed_by": { "const": "client" } } }] } }, "said_only": { "const": true }, "tool_results_sent": { "type": "array", "maxItems": 1024, "items": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" } }, "tool_results": { "type": "array", "maxItems": 1024, "items": { "type": "object", "additionalProperties": false, "required": ["id", "forms"], "properties": { "id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "forms": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "object", "additionalProperties": false, "required": ["digest", "result_digest"], "properties": { "digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "result_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" } } } } } } }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "amended": { "type": "array", "minItems": 1, "maxItems": 16, "items": { "type": "string", "maxLength": 256, "pattern": "^(/([^~/]|~[01])*)+(?![\\s\\S])" } }, "body": {} } },
     "approval_request": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "tool_call_id"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "tool_call_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "attempt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reason": { "type": "string", "maxLength": 1024 } } },
     "approval_decide": { "type": "object", "additionalProperties": false, "required": ["request_id", "approval_id", "decision"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "approval_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "decision": { "enum": ["approve", "reject", "escalate"] }, "reason": { "type": "string", "maxLength": 1024 }, "on_behalf": { "type": "object", "additionalProperties": false, "required": ["subject", "person"], "properties": { "subject": { "type": "string", "maxLength": 256, "minLength": 1 }, "person": { "type": "string", "maxLength": 256, "minLength": 1 }, "groups": { "type": "array", "maxItems": 64, "items": { "type": "string", "maxLength": 256 } }, "tenant": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" } } }, "passkey": { "type": "object", "additionalProperties": false, "required": ["credential_id", "client_data_json", "authenticator_data", "signature"], "properties": { "credential_id": { "type": "string", "maxLength": 4096, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+(?![\\s\\S])" }, "client_data_json": { "type": "string", "maxLength": 4096, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+(?![\\s\\S])" }, "authenticator_data": { "type": "string", "maxLength": 4096, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+(?![\\s\\S])" }, "signature": { "type": "string", "maxLength": 4096, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+(?![\\s\\S])" } } }, "asserted": { "type": "object", "additionalProperties": false, "required": [], "properties": { "model": { "type": "string", "maxLength": 128 }, "version": { "type": "string", "maxLength": 64 }, "prompt_hash": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" } } } } },
     "approval_decide_on_behalf": { "type": "object", "additionalProperties": false, "required": ["request_id", "approval_id", "decision", "approver"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "approval_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "decision": { "enum": ["approve", "reject"] }, "approver": { "type": "string", "maxLength": 64, "pattern": "^slack:[A-Z0-9]+/[A-Z0-9]+(?![\\s\\S])" }, "groups": { "type": "array", "maxItems": 32, "items": { "type": "string", "maxLength": 64, "pattern": "^slack:[A-Z0-9]+/[A-Z0-9]+(?![\\s\\S])" } } } },
@@ -21,7 +21,7 @@ export const REQUESTS = {
     "delegate_run": { "type": "object", "additionalProperties": false, "required": ["run_id", "run_token", "identity"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "identity": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" } } },
     "tailer_lost": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "reason", "offset"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "reason": { "type": "string", "maxLength": 1024 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } },
     "tailer_heartbeat": { "type": "object", "additionalProperties": false, "required": ["run_id", "run_token"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 } } },
-    "observe_effect": { "type": "object", "additionalProperties": false, "required": ["request_id", "instance", "effects"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "instance": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "effects": { "type": "array", "maxItems": 256, "items": { "type": "object", "additionalProperties": false, "required": ["kind", "host", "port", "bytes_out", "bytes_in", "connections", "first_ts", "last_ts"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "kind": { "const": "net" }, "host": { "type": "string", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9._:-]+(?![\\s\\S])" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "bytes_out": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "bytes_in": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "connections": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "first_ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" }, "last_ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" } } } }, "check": { "type": "object", "additionalProperties": false, "required": ["run_id", "run_token"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 } } } } },
+    "observe_effect": { "type": "object", "additionalProperties": false, "required": ["request_id", "instance", "effects"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "instance": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "effects": { "type": "array", "maxItems": 256, "items": { "oneOf": [{ "type": "object", "additionalProperties": false, "required": ["kind", "host", "port", "bytes_out", "bytes_in", "connections", "first_ts", "last_ts"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "kind": { "const": "net" }, "host": { "type": "string", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9._:-]+(?![\\s\\S])" }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "bytes_out": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "bytes_in": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "connections": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "first_ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" }, "last_ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "ts", "pid", "binary"], "properties": { "kind": { "const": "exec" }, "args_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "parent_exec_id": { "type": "string", "maxLength": 256, "minLength": 1 }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" }, "pid": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "binary": { "type": "string", "maxLength": 4096, "minLength": 1 }, "exec_id": { "type": "string", "maxLength": 256, "minLength": 1 }, "tool_call_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "denied": { "const": true } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "ts", "pid", "binary"], "properties": { "kind": { "const": "exit" }, "status": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "signal": { "type": "string", "maxLength": 32 }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" }, "pid": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "binary": { "type": "string", "maxLength": 4096, "minLength": 1 }, "exec_id": { "type": "string", "maxLength": 256, "minLength": 1 }, "tool_call_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "denied": { "const": true } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "ts", "pid", "binary", "host", "port"], "properties": { "kind": { "const": "connect" }, "host": { "type": "string", "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9._:-]+(?![\\s\\S])" }, "port": { "type": "integer", "minimum": 0, "maximum": 65535 }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" }, "pid": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "binary": { "type": "string", "maxLength": 4096, "minLength": 1 }, "exec_id": { "type": "string", "maxLength": 256, "minLength": 1 }, "tool_call_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "denied": { "const": true } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "ts", "pid", "binary", "path"], "properties": { "kind": { "const": "file" }, "path": { "type": "string", "maxLength": 4096, "minLength": 1 }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" }, "ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" }, "pid": { "type": "integer", "minimum": 0, "maximum": 4294967295 }, "binary": { "type": "string", "maxLength": 4096, "minLength": 1 }, "exec_id": { "type": "string", "maxLength": 256, "minLength": 1 }, "tool_call_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "denied": { "const": true } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "ts", "change"], "properties": { "kind": { "const": "policy" }, "ts": { "type": "string", "maxLength": 27, "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{6}Z(?![\\s\\S])" }, "change": { "type": "string", "maxLength": 64, "minLength": 1, "pattern": "^[a-z0-9_.-]+(?![\\s\\S])" }, "policy_hash": { "type": "string", "maxLength": 128, "minLength": 1 }, "by": { "type": "string", "maxLength": 256, "minLength": 1 }, "detail_digest": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "reason"], "properties": { "kind": { "const": "lost" }, "reason": { "type": "string", "maxLength": 1024, "minLength": 1 }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "caller": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" } } }] } }, "check": { "type": "object", "additionalProperties": false, "required": ["run_id", "run_token"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 } } }, "sensor": { "enum": ["tetragon", "falco", "openshell"] }, "callers": { "type": "array", "maxItems": 256, "items": { "type": "string", "maxLength": 256, "pattern": "^[a-z0-9_]+:.+(?![\\s\\S])" } }, "lost": { "type": "string", "maxLength": 1024 } } },
     "status": { "type": "object", "additionalProperties": false, "required": [], "properties": {} },
     "read": { "type": "object", "additionalProperties": false, "required": ["run_id", "run_token"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "from_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000 } } },
     "checkpoint_nudge": { "type": "object", "additionalProperties": false, "required": [], "properties": {} },
@@ -30,6 +30,8 @@ export const REQUESTS = {
     "content_get": { "type": "object", "additionalProperties": false, "required": ["run_id", "seqs", "purpose"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "seqs": { "type": "array", "maxItems": 1000, "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "purpose": { "type": "string", "maxLength": 512, "minLength": 1 } } },
     "content_erase": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "reason": { "type": "string", "maxLength": 1024 } } },
     "why_finding": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "finding"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "finding": { "type": "object", "additionalProperties": false, "required": ["target", "intervention", "n", "p_with", "p_without", "effect", "interval", "verdict", "replay_runs", "models", "rung", "off_tape", "investigation", "looks", "family", "min_effect", "applied", "stopped"], "properties": { "target": { "type": "string", "maxLength": 1024 }, "intervention": { "type": "string", "maxLength": 1024 }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "p_with": { "type": "number", "minimum": 0, "maximum": 1 }, "p_without": { "type": "number", "minimum": 0, "maximum": 1 }, "effect": { "type": "number", "minimum": -1, "maximum": 1 }, "interval": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number", "minimum": -1, "maximum": 1 } }, "verdict": { "enum": ["causal", "suppressive", "ruled-out", "inconclusive", "not-applied"] }, "replay_runs": { "type": "array", "maxItems": 4096, "items": { "type": "object", "additionalProperties": false, "required": ["run_id", "arm", "hit"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "arm": { "enum": ["control", "ablated"] }, "hit": { "type": "boolean" } } } }, "models": { "type": "array", "maxItems": 32, "items": { "type": "string", "maxLength": 128 } }, "rung": { "enum": [1, 2] }, "off_tape": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "investigation": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "looks": { "type": "integer", "minimum": 1, "maximum": 4096 }, "family": { "type": "integer", "minimum": 1, "maximum": 4096 }, "min_effect": { "type": "number", "minimum": 0, "maximum": 1 }, "applied": { "type": "boolean" }, "stopped": { "enum": ["decisive", "futility", "n_max", "budget"] }, "uncounted": { "type": "array", "maxItems": 4096, "items": { "type": "object", "additionalProperties": false, "required": ["run_id", "reason"], "properties": { "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "reason": { "enum": ["ranking", "budget"] } } } } } } } },
+    "review_finding": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "review"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "review": { "type": "object", "additionalProperties": false, "required": ["reviewer", "verdict", "cites"], "properties": { "reviewer": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._/+-]+(?![\\s\\S])" }, "cites": { "type": "array", "maxItems": 256, "items": { "type": "object", "additionalProperties": false, "required": ["run_seq", "hash"], "properties": { "run_seq": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "hash": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" } } } }, "verdict": { "oneOf": [{ "type": "object", "additionalProperties": false, "required": ["kind", "rule", "severity"], "properties": { "kind": { "const": "finding" }, "rule": { "enum": ["TK-X201", "TK-X202", "TK-X203", "TK-X204", "TK-X205", "TK-X206", "TK-X207", "TK-X208", "TK-X210", "TK-X101", "TK-X102", "TK-X103", "TK-X104", "TK-X111", "TK-X112", "TK-X113", "TK-X114", "TK-X120", "TK-X211"] }, "severity": { "enum": ["info", "low", "medium", "high", "critical"] }, "tier": { "enum": ["gateway", "harness", "transcript", "sdk"] }, "order": { "enum": ["signed_before", "transcript_order", "after"] }, "redacted": { "type": "boolean" }, "lifted": { "type": "boolean" }, "digests": { "type": "array", "maxItems": 32, "items": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" } }, "alignment": { "enum": ["ok", "drift", "misaligned"] }, "reason": { "enum": ["none", "unrequested_action", "unexplained_action", "contradicted_reasoning", "scope_creep", "workaround", "false_success", "followed_tool_output", "injection", "other"] }, "asserted": { "type": "object", "additionalProperties": false, "required": ["model", "version", "prompt_hash"], "properties": { "model": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:/@+-]+(?![\\s\\S])" }, "version": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:/@+-]+(?![\\s\\S])" }, "prompt_hash": { "type": "string", "maxLength": 71, "pattern": "^sha256:[0-9a-f]{64}(?![\\s\\S])" } } }, "families": { "type": "object", "additionalProperties": false, "required": ["reviewer", "agent"], "properties": { "reviewer": { "enum": ["anthropic", "openai", "google", "meta", "mistral", "deepseek", "qwen", "xai", null] }, "agent": { "type": "array", "maxItems": 8, "items": { "enum": ["anthropic", "openai", "google", "meta", "mistral", "deepseek", "qwen", "xai"] } } } }, "window": { "type": "object", "additionalProperties": false, "required": ["grace_s", "skew_s"], "properties": { "grace_s": { "type": "number", "minimum": 0, "maximum": 86400 }, "skew_s": { "type": "number", "minimum": 0, "maximum": 86400 } } } } }, { "type": "object", "additionalProperties": false, "required": ["kind", "rule", "severity", "checks"], "properties": { "kind": { "const": "coverage" }, "rule": { "const": "TK-X200" }, "severity": { "const": "info" }, "checks": { "type": "object", "additionalProperties": false, "required": [], "properties": { "TK-X201": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X202": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X203": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X204": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X205": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X206": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X207": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X208": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X210": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X101": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X102": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X103": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X104": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X111": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X112": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X113": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X114": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X120": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } }, "TK-X211": { "type": "object", "additionalProperties": false, "required": ["checked", "found"], "properties": { "checked": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "found": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "not_checkable": { "type": "array", "maxItems": 16, "items": { "type": "object", "additionalProperties": false, "required": ["reason", "n"], "properties": { "reason": { "type": "string", "maxLength": 32, "minLength": 1, "pattern": "^[a-z][a-z_]*(?![\\s\\S])" }, "n": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } } } } }, "partial": { "type": "boolean" }, "reasoning": { "type": "object", "additionalProperties": false, "required": [], "properties": { "full": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "summary": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "withheld": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "none": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } } }] } } } } },
+    "constraint_add": { "type": "object", "additionalProperties": false, "required": ["request_id", "run_id", "run_token", "constraint"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "run_token": { "type": "string", "maxLength": 1024, "minLength": 1 }, "constraint": { "type": "object", "additionalProperties": false, "required": ["kind"], "properties": { "kind": { "enum": ["keep_away", "only_change", "read_only", "no_push", "no_network"] }, "object": { "type": "string", "maxLength": 256, "minLength": 1 } } } } },
     "incident_list": { "type": "object", "additionalProperties": false, "required": [], "properties": { "state": { "enum": ["open", "resolved"] }, "cursor": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000 } } },
     "incident_show": { "type": "object", "additionalProperties": false, "required": ["incident_id"], "properties": { "incident_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" } } },
     "incident_resolve": { "type": "object", "additionalProperties": false, "required": ["request_id", "incident_id"], "properties": { "request_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "incident_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9._:-]+(?![\\s\\S])" }, "reason": { "type": "string", "maxLength": 1024 } } },

package/dist/verify/cli.js

@@ -3,6 +3,7 @@
  * CLI's report and exit codes (0 verified, 1 failed, 2 unusable or unverifiable, 3 a warning under --strict).
  */
 import { readFile } from "node:fs/promises";
+import { asJson } from "./explain.js";
 import { EXIT_BAD, EXIT_OK, EXIT_WARN, formatReport, verify } from "./index.js";
 const USAGE = "usage: tracekit verify BUNDLE --trust TRUST.json [--json] [--strict]";
 export async function main(argv) {
@@ -19,7 +20,7 @@ export async function main(argv) {
             bundle = a;
         else {
             console.error(`tracekit verify: ${a} is not supported by the TypeScript verifier (the format bridge, monitor reports `
-                + `and revocations need the reference verifier: pip install tracekit)\n${USAGE}`);
+                + `and revocations need the reference verifier: pip install tracekit-ai)\n${USAGE}`);
             return EXIT_BAD;
         }
     }
@@ -35,11 +36,10 @@ export async function main(argv) {
         console.error(`tracekit verify: ${e.message}`);
         return EXIT_BAD;
     }
-    const { report, code: verdict } = await verify(...data);
+    const { report, code: verdict } = await verify(...data, { bundle, trust });
     const code = verdict === EXIT_OK && strict && report.warnings.length ? EXIT_WARN : verdict;
     if (json)
-        console.log(JSON.stringify({ exit_code: code, checks: report.checks, failures: report.failures,
-            warnings: report.warnings, integrity: report.integrity, assurance: report.assurance, notes: report.notes }, null, 2));
+        console.log(JSON.stringify(asJson(report, code), null, 2));
     else
         process.stdout.write(formatReport(report));
     return code;

package/dist/verify/explain.d.ts

@@ -0,0 +1,46 @@
+/**
+ * What the browser verifier (web.ts) says about a report, in plain words: the verdict and what it does and doesn't
+ * mean, what to do next, a line per check on what it means (docs/verdicts.md, shortened), and a summary of the bundle's
+ * runs. The report itself is the CLI's, unchanged: this module only reads it. No DOM, so Node tests it.
+ */
+import { type Report } from "./index.js";
+export type Names = {
+    bundle: string;
+    trust: string | null;
+};
+export type Verdict = {
+    word: "VERIFIED" | "FAILED" | "UNVERIFIABLE";
+    means: string;
+    notMeans: string;
+};
+/** A step: what to do, and the command to run for it, if any. */
+export type Step = {
+    text: string;
+    command?: string;
+};
+/** `s` as one shell argument (POSIX shells; the page doesn't know the reader's). */
+export declare const sh: (s: string) => string;
+/** The report as `tracekit verify --json` prints it (cli.ts prints this). */
+export declare const asJson: (rep: Report, code: number) => {
+    findings?: string | undefined;
+    exit_code: number;
+    checks: import("./index.js").Check[];
+    failures: string[];
+    warnings: string[];
+    integrity: string;
+    assurance: string;
+    notes: string[];
+};
+/** The report as `tracekit verify` prints it, then its exit code. */
+export declare const asText: (rep: Report, code: number) => string;
+/** What the command-line verifiers exit with for the same files, where that is known: they refuse a v2 bundle without a
+ * trust file, and the Python one checks what this verifier doesn't (and v1 bundles, against signer.pub). */
+export declare function cliExit(rep: Report): string;
+export declare function verdict(rep: Report, code: number): Verdict;
+/** What to do after a result that isn't plainly VERIFIED: what to check or ask for, with the commands that do it. */
+export declare function nextSteps(rep: Report, code: number, names: Names): Step[];
+/** One line per check: what it means (docs/verdicts.md#lines). */
+export declare const MEANING: Record<string, string>;
+/** A few plain facts about the bundle's runs, from their records ({name: bytes}, the runs/ files, a run's parts read as
+ * one), cleaned as the report is; names an agent chose are quoted, so they can't read as the signer's words around them. */
+export declare function summarize(files: Map<string, Uint8Array>, rep: Report): [string, string][];

package/dist/verify/explain.js

@@ -0,0 +1,212 @@
+/**
+ * What the browser verifier (web.ts) says about a report, in plain words: the verdict and what it does and doesn't
+ * mean, what to do next, a line per check on what it means (docs/verdicts.md, shortened), and a summary of the bundle's
+ * runs. The report itself is the CLI's, unchanged: this module only reads it. No DOM, so Node tests it.
+ */
+import { EXIT_FAIL, EXIT_OK, VERSION, clean, formatReport, runFiles } from "./index.js";
+/** `s` as one shell argument (POSIX shells; the page doesn't know the reader's). */
+export const sh = (s) => /^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'"'"'`)}'`;
+const TRUST_FILE = "the sender's trust file: a small .json that names their signer's log key (tracekit last writes it next "
+    + "to the bundle, as <name>.trust.json)";
+/** The report as `tracekit verify --json` prints it (cli.ts prints this). */
+export const asJson = (rep, code) => ({ exit_code: code, checks: rep.checks, failures: rep.failures,
+    warnings: rep.warnings, integrity: rep.integrity, assurance: rep.assurance, notes: rep.notes,
+    ...rep.findings ? { findings: rep.findings } : {} });
+/** The report as `tracekit verify` prints it, then its exit code. */
+export const asText = (rep, code) => formatReport(rep) + `\nExit code ${code}`
+    + (code === EXIT_OK && rep.warnings.length ? ` (3 with --strict: ${rep.warnings.length} warning(s))` : "") + ".\n";
+const failed = (rep, name) => rep.checks.find((c) => c.check === name && c.status === "fail");
+const anchored = (rep) => !rep.checks.some((c) => c.check === "trust config" && c.status === "warn");
+const v1 = (rep) => rep.checks.some((c) => c.check === "bundle readable"
+    && c.problems.some((p) => p.startsWith("a format v1 bundle")));
+/** What the command-line verifiers exit with for the same files, where that is known: they refuse a v2 bundle without a
+ * trust file, and the Python one checks what this verifier doesn't (and v1 bundles, against signer.pub). */
+export function cliExit(rep) {
+    if (v1(rep))
+        return "";
+    if (!anchored(rep))
+        return " The command-line verifiers need the trust file: without one they exit 2.";
+    return rep.unsupported.length ? " The TypeScript command-line verifier exits with the same code; the Python one checks "
+        + "what this page doesn't." : " The command-line verifiers exit with the same code.";
+}
+export function verdict(rep, code) {
+    const behaved = "It doesn't mean the agent behaved well, or that the record holds everything it did: the summary, "
+        + "findings and warnings below tell you that.";
+    if (code === EXIT_OK) {
+        const head = rep.integrity.match(/^VERIFIED TO HEAD (\d+)/);
+        return { word: "VERIFIED", means: "The record is intact and signed by the signer your trust file names: nothing was "
+                + "edited, removed, reordered or added after signing."
+                + (head ? ` The run was still open when it was exported: its records up to number ${head[1]} are verified.` : ""),
+            notMeans: behaved };
+    }
+    if (code === EXIT_FAIL) {
+        if (failed(rep, "checkpoint") && anchored(rep))
+            return { word: "FAILED", means: "This bundle is not signed by the signer your trust file names, or its checkpoint "
+                    + "was changed.", notMeans: "It doesn't say who made the bundle. If the trust file is the right one, don't rely "
+                    + "on the bundle." };
+        return { word: "FAILED", means: "This bundle doesn't match what was signed: something in it was changed, removed or "
+                + `added after signing. Failed: ${rep.failures.join(", ")}.`,
+            notMeans: "It doesn't say who changed it or why: the failed lines below show what doesn't match." };
+    }
+    const readable = rep.checks.find((c) => c.check === "bundle readable");
+    const nothing = "Nothing failed: it doesn't mean the bundle is bad.";
+    if (failed(rep, "trust config"))
+        return { word: "UNVERIFIABLE", means: "The trust file couldn't be used, so nothing was checked.", notMeans: nothing };
+    if (v1(rep))
+        return { word: "UNVERIFIABLE", means: "This is a format v1 bundle (from Tracekit's laptop signer); this page checks "
+                + "format v2 bundles, so nothing was checked.", notMeans: nothing };
+    if (rep.integrity.startsWith("UNVERIFIABLE (needs"))
+        return { word: "UNVERIFIABLE", means: `This bundle needs a newer verifier than this page (Tracekit ${VERSION}).`,
+            notMeans: nothing };
+    if (readable)
+        return { word: "UNVERIFIABLE", means: "This file couldn't be read as a Tracekit bundle, so nothing in it was checked.",
+            notMeans: "Nothing in it can be relied on until a readable copy verifies." };
+    if (!anchored(rep))
+        return { word: "UNVERIFIABLE", means: "Signatures are intact, but you haven't said whose signer you trust.",
+            notMeans: "It doesn't mean the bundle is genuine: anyone can sign a bundle with keys of their own. The sender's "
+                + "trust file says whose signer made it." };
+    return { word: "UNVERIFIABLE", means: "This page doesn't implement a check this bundle relies on: "
+            + `${rep.integrity.replace(/^UNVERIFIABLE \(not checked by this verifier: (.*)\)$/, "$1")}.`, notMeans: nothing };
+}
+/** What to do after a result that isn't plainly VERIFIED: what to check or ask for, with the commands that do it. */
+export function nextSteps(rep, code, names) {
+    const b = sh(names.bundle), t = sh(names.trust ?? "trust.json");
+    const cli = { text: "Check the same files with the command-line verifier (it needs Node.js, nothing else):",
+        command: `npx -y @cygnuxlabs/tracekit@latest verify ${b} --trust ${t}` };
+    const readable = rep.checks.find((c) => c.check === "bundle readable");
+    if (code === EXIT_OK)
+        return rep.warnings.length ? [{ text: `Read the ${rep.warnings.length} warning(s) below: each says what to look at. `
+                    + "They don't change the verdict (with --strict the command line exits 3)." }] : [];
+    if (failed(rep, "trust config"))
+        return [{ text: `Choose the trust file again: it must be a Tracekit v2 trust config (a .json with "logs"). Ask for ${TRUST_FILE}.` }];
+    if (readable?.problems.length)
+        return readable.problems.map((p) => {
+            const at = p.search(/(npx|uvx) /);
+            const text = at < 0 ? p.replace(/^or open (\S+) /, "open the latest page, $1, ")
+                : at ? p.slice(0, at).trimEnd() : p.startsWith("npx") ? "with Node.js:" : "or with Python, using uv:";
+            return { text: text[0].toUpperCase() + text.slice(1), ...at < 0 ? {} : { command: p.slice(at) } };
+        });
+    if (readable)
+        return [{ text: `Check that you chose the .tkb file itself (not a renamed archive or a saved web page), then ask the `
+                    + "sender to export it again: a damaged or cut-short copy reads like this." }];
+    if (code === EXIT_FAIL) {
+        const steps = [];
+        if (failed(rep, "checkpoint") && anchored(rep))
+            steps.push({ text: `Make sure the trust file is ${TRUST_FILE.replace("the sender's", "the sender's own")}. With `
+                    + "the right one, this bundle isn't theirs: don't rely on it." });
+        else
+            steps.push({ text: "Don't rely on this bundle's contents. Ask the sender for the original and compare its SHA-256 "
+                    + "with theirs:", command: `shasum -a 256 ${b}` });
+        if (anchored(rep))
+            steps.push(cli);
+        else
+            steps.push({ text: `Add ${TRUST_FILE}, to see whose signer made it.` });
+        return steps;
+    }
+    if (!anchored(rep))
+        return [{ text: `Ask for ${TRUST_FILE}, and add it above. Get it from the sender directly, not inside the bundle's `
+                    + "own folder or message: the trust file is what makes the check mean something." }];
+    return [{ text: "Verify it with the reference verifier, which checks this:",
+            command: `uvx --from tracekit-ai tracekit verify ${b} --trust ${t}` }];
+}
+/** One line per check: what it means (docs/verdicts.md#lines). */
+export const MEANING = {
+    "trust config": "Your trust file: the log key and witnesses you trust, never ones the bundle brings.",
+    "bundle readable": "The file is a Tracekit v2 bundle this verifier can read.",
+    "bundle structure": "The bundle is well formed; a failure here means it is malformed in a way no other line covers.",
+    "manifest": "The files in the bundle are exactly those its manifest lists, with those hashes.",
+    "checkpoint": "The log's checkpoint (the signed root of every record) is signed by the log key your trust file pins.",
+    "witness quorum": "Enough witnesses your trust file pins cosigned the checkpoint: they vouch it was not rolled back.",
+    "keys": "The record keys were declared by records the checkpoint includes, in order, and retired keys stop signing.",
+    "run parts": "A long run comes in numbered parts: none is missing between the first and the last, extra or out of "
+        + "order, so they read as one run. Parts cut off its end leave it open, never VERIFIED.",
+    "signatures": "Every record's signature verifies under a key valid at its position: no record was edited after signing.",
+    "run chain": "Each run's records follow one another without a gap from the first: none deleted, swapped or added.",
+    "inclusion": "Each run's first and last records are in the checkpointed tree: the run wasn't rebuilt.",
+    "policy snapshot": "The bundled policy file is named by its own hash: it wasn't edited.",
+    "policy": "A tool call ran against a deny, or an ask nobody approved, and the signer recorded it.",
+    "held calls": "A call held for a gateway or executor got no result before its run ended.",
+    "gaps": "The signer recorded something a person should read: a gap, a tamper attempt or a mismatched approval.",
+    "external decisions": "Decisions imported from another policy system, and whether they disagreed with the signer's.",
+    "coverage": "Which capture layers reported, and calls the signer could not match across them.",
+    "coverage matrix": "How each kind of action was covered: enforced, observed, only reported by the agent, or not at all.",
+    "observers": "An observer outside the agent went silent or restarted while the run was open.",
+    "reviews": "Signed findings about the run, each labelled by who wrote it: independent, unpinned or self-asserted.",
+    "reviews counted": "Findings whose analysed run isn't in the bundle, so their citations weren't checked.",
+    "incidents": "Detections the signer opened, recomputed from the run's records where the bundle allows.",
+    "incident policies": "Policies an incident cites that aren't in the bundle: those incidents are the signer's word.",
+    "content vault": "Who read or erased retained content, as the signer recorded it.",
+    "tiers": "Tool calls by how they were captured: T2 gateway or executor, T1 adapter, T3 import (receipt only).",
+    "args source": "Whether recorded arguments are the model's exact bytes (raw), parsed, or changed by a framework.",
+    "isolation": "How the signer measured its separation from the agent: separate-user and remote are out of its reach.",
+    "principals": "The person or service each run acted for, attested by the signer or asserted by the app.",
+    "harness": "The agent harness the signer bound each run to.",
+    "fail-open classes": "Tool classes allowed to run while the signer is down, so such calls may be unrecorded.",
+    "key assurance": "Whether the record keys are only declared by the log (asserted) or certified by an issuer.",
+    "approvals by people": "Held calls approved by people.",
+    "approvals by agents": "Held calls approved by agents (model output), checked against the rules that allow it.",
+    "break-glass approvals": "Approvals given under the break-glass role, with who and why.",
+    "not interpreted": "Records carry an extension this verifier doesn't read. They verified like every other record.",
+    "gateway amendments": "Requests the LLM gateway changed so the provider shows its reasoning; each record commits to "
+        + "the request as sent.",
+    "openshell policy": "Changes of the sandbox's policy or configuration that NVIDIA OpenShell reported, signed into "
+        + "the run as OpenShell's report.",
+    "constraints": "What the person's request said not to do, added while the run was open, and the calls it held.",
+    "run-set": "Every run of the tenant in the registry range is in the bundle (COMPLETE), or what is missing.",
+    "tenant-level gaps": "Signer gaps in the range that concern every tenant, such as witness failures.",
+    "log tail": "Whether records after the checkpoint are proven absent (a log.closed) or simply unproven.",
+    "rekor anchor": "A Rekor transparency-log anchor of the checkpoint, which this page can't check.",
+    "SLH-DSA-SHA2-128s checkpoint signature": "A post-quantum checkpoint signature, which browsers can't check yet.",
+    "record-key certificates": "Certificates of the record keys, which this page doesn't check.",
+    "tracekit why findings": "tracekit why investigation findings, which this page doesn't check.",
+};
+const day = (ts) => ts.slice(0, 19).replace("T", " ") + " UTC";
+/** A few plain facts about the bundle's runs, from their records ({name: bytes}, the runs/ files, a run's parts read as
+ * one), cleaned as the report is; names an agent chose are quoted, so they can't read as the signer's words around them. */
+export function summarize(files, rep) {
+    const text = new TextDecoder();
+    const runs = [...runFiles(files.keys()).values()].map((parts) => parts.flatMap((n) => text.decode(files.get(n))
+        .split("\n").filter(Boolean).map((l) => JSON.parse(l).event)));
+    const events = runs.flat(), of = (t) => events.filter((e) => e.type === t);
+    const times = events.map((e) => e.ts).filter((t) => typeof t === "string").sort();
+    const out = [];
+    const [first, end] = [times[0], times[times.length - 1]], secs = (Date.parse(end) - Date.parse(first)) / 1000;
+    out.push(["Records", `${events.length} signed record(s) in ${runs.length} run(s)` + (times.length ? `, ${day(first)}`
+            + ` to ${day(end)} (${secs < 120 ? `${Math.round(secs)} s` : secs < 7200 ? `${Math.round(secs / 60)} min`
+                : `${Math.round(secs / 3600)} h`})` : "")]);
+    const cp = rep.checks.find((c) => c.check === "checkpoint")?.detail.split(" at tree size")[0];
+    if (cp)
+        out.push(["Signer", `log ${cp}` + (anchored(rep) ? ", the key your trust file pins" : ", not checked (no trust file)")]);
+    const level = rep.assurance.split(";")[0];
+    out.push(["Assurance", level === "witnessed" ? "witnessed: independent witnesses cosigned the checkpoint"
+            : level === "local" ? "local: only witnesses the log's operator runs cosigned the checkpoint"
+                : level === "dev" ? "dev: no independent witness vouches for the checkpoint (or a run holds a self-approval)"
+                    : level]);
+    const agents = runs.map((rs) => rs[0]).filter((e) => e?.type === "run.registered").map((e) => {
+        const id = e.data?.identity;
+        return `${JSON.stringify(String(e.data?.agent?.name ?? "agent"))}` + (id ? ` (${id.scheme}:${id.subject})` : "");
+    });
+    const named = [...new Set(agents)];
+    if (named.length)
+        out.push(["Agents", named.slice(0, 5).join(", ") + (named.length > 5 ? ", ..." : "")]);
+    const decisions = of("policy.decision").map((e) => e.data?.decision);
+    out.push(["Tool calls", `${decisions.length} decided` + (decisions.length ? ": " + ["allow", "deny", "ask"]
+            .map((d) => `${decisions.filter((x) => x === d).length} ${d}`).join(", ") : "")]);
+    const answers = new Map(of("approval").map((e) => [e.data?.approval_id, e.data]));
+    const held = of("approval.request").map((e) => {
+        const a = answers.get(e.data?.approval_id);
+        const who = a ? `${a.decision === "approve" ? "approved" : a.decision === "reject" ? "rejected" : a.decision} by `
+            + `${a.person ?? a.approver}` + (a.approver_kind === "agent" ? " (an agent)" : "")
+            + (a.self_approved ? " (self-approved)" : "") + (a.break_glass ? " (break-glass)" : "") : "no answer recorded";
+        const tool = e.data?.binding?.tool ?? e.tool_call_id;
+        return `${tool == null ? "a call" : JSON.stringify(String(tool))}: ${who}`;
+    });
+    out.push(["Held for approval", held.length ? held.slice(0, 10).join("; ") + (held.length > 10 ? "; ..." : "") : "none"]);
+    const gaps = new Map();
+    for (const e of of("capture.gap"))
+        gaps.set(e.data?.kind, (gaps.get(e.data?.kind) ?? 0) + 1);
+    out.push(["Gaps", gaps.size ? [...gaps].map(([k, n]) => `${k} ${n}`).join(", ") : "none recorded"]);
+    const findings = ["reviews", "incidents"].map((n) => rep.checks.find((c) => c.check === n)?.detail).filter(Boolean);
+    out.push(["Findings", findings.length ? findings.join("; ") : "none recorded"]);
+    return out.map(([k, v]) => [k, clean(v)]);
+}