{
  "markdown": "# Warrant\n\n**When a machine says something was allowed, can you check why — without\ntrusting the machine that allowed it?**\n\nWarrant is a small, signed, content-addressed decision record. It names what was\ndecided, the exact policy bytes in force, the reasons and evidence, the actor,\nand the decisions that came before it. An executable reason can be re-run by the\nreader instead of trusted as a log entry.\n\n```json\n{\n  \"decision\": \"reject\",\n  \"subject\": {\"hash\": \"d5cf37…\", \"note\": \"PR-42\"},\n  \"under\": [\"cb3a0a…\"],\n  \"because\": [\n    {\"kind\": \"check\", \"check\": \"05d234…\", \"runtime\": \"cmd@v1\",\n     \"verdict\": \"fail\", \"transcript\": \"9dc0c3…\"},\n    {\"kind\": \"prose\", \"text\": \"policy clause 1: coverage drops\"}\n  ],\n  \"evidence\": [\"9dc0c3…\"],\n  \"actor\": {\"id\": \"agent-b@vendor2\"},\n  \"prior\": [\"00f79f…\"],\n  \"ts\": 1751677200\n}\n```\n\nThe canonical body hash is the record's identity. Changing the decision,\npolicy reference, reason, evidence or prior edge changes that identity. The\nsignature says which key signed the body; whether that key belongs to the named\nactor is a separate trust-configuration question. A rejection is a durable\nrecord, not an absence.\n\nWarrant is not an agent framework, blockchain or observability system. It is one\nfile format and five filing verbs, designed to be boring.\n\nThe format is written up in *The Reason Runs Again*\n([10.5281/zenodo.22172098](https://doi.org/10.5281/zenodo.22172098), paper\nv1.0.0, 2026-08-30 — deposited, not peer reviewed; see\n[`papers/`](papers/README.md)).\n\n## Try it\n\n```bash\npipx install warrant-verify   # or: pip install warrant-verify\n\nwarrant init\nwarrant keygen --out me.key\nprintf 'demo diff\\n' > diff.patch\nprintf 'clause 1: no coverage drop\\n' > policy.txt\nprintf '#!/bin/sh\\nexit 1\\n' > check.sh && chmod +x check.sh\n\nPOL=$(warrant policy add policy.txt)\nP=$(warrant propose --subject diff.patch --under \"$POL\" \\\n      --reason \"utility functions needed\" --actor me@host --key me.key)\nR=$(warrant reject \"$P\" --check check.sh --verdict fail \\\n      --reason \"clause 1: coverage drop\" --actor me@host --key me.key)\nprintf '#!/bin/sh\\nexit 0\\n' > check.sh\nA=$(warrant accept \"$R\" --check check.sh --verdict pass \\\n      --actor me@host --key me.key)\n\nwarrant why \"$A\"\nwarrant verify\n```\n\nEvery file used above is created above. The final warnings say that the key-to-\nactor binding is unverified until a trust configuration supplies that authority;\na valid signature is not silently promoted into a valid identity claim.\n\nThe `warrant-verify` distribution installs four commands:\n\n- `warrant` — file, inspect and verify decisions;\n- `warrant-mcp-server` — let an MCP client file its own decisions;\n- `warrant-mcp` — seal calls passing through another MCP server;\n- `warrant-anchor` — batch WarrantIDs into a Merkle anchor.\n\n`ski@v1` reasons replay offline through one bundled Σ-GLYPH Book I v0.5\nevaluator, pinned by digest and checked before import. Reserved `ski@v2` is not\nadmitted by any body version and ships no executable candidate bytes.\n\nThe longer walkthrough, including negative controls, is\n[`docs/try-this-in-fifteen-minutes.md`](docs/try-this-in-fifteen-minutes.md).\n\n## Machine boundary\n\nFor CI, MCP or an agent framework, verify an initialized store with\n`--store-mode --json`:\n\n```sh\nwarrant --store ./evidence-pack/.warrants verify --store-mode --json | jq -e '.ok'\nwarrant-go verify --store-mode --json ./evidence-pack/.warrants | jq -e '.ok'\n```\n\n```json\n{\"report\":\"warrant.verify-report@v0\",\"grade\":\"base\",\"ok\":true,\n \"records\":3,\"errors\":0,\"warnings\":1,\n \"findings\":[{\"level\":\"WARN\",\"subject\":\"<WarrantID>\",\"message\":\"...\"}]}\n```\n\n`--store-mode` is part of the safe predicate: a missing or uninitialized store\nfails closed instead of looking like an empty successful verification. Python\ntakes the store through the global `--store`; Go takes it positionally.\n\nConsumers may rely on these boundaries:\n\n- `ok == (errors == 0)`, and the error/warning counts equal the corresponding\n  findings;\n- `warrant.verify-report@v0` is closed: seven top-level fields and\n  `{level, subject, message}` findings;\n- Python and Go agree on normative fields and `(level, subject)` pairs; `message`\n  is human prose and may differ;\n- `grade` distinguishes `base` from `settlement`;\n- the report is unsigned and carries **no Warrant authority**.\n\nThe normative contract is [`SPEC.md` §11](SPEC.md#11-verification-report--warrantverify-reportv0),\nwith [`schemas/verify-report-v0.schema.json`](schemas/verify-report-v0.schema.json)\nalongside. `tools/check_release_surface.py` fails CI and publishing when the\ndocumented CLI surface is absent from the checkout or built wheel.\n\n## Re-execute a real specimen\n\nThe Air Canada specimen is an authored reconstruction of the decision record\nthe airline did not have; it is not evidence produced by Air Canada.\n\n```bash\npipx install warrant-verify==0.9.0\ncurl -LO https://github.com/s0fractal/warrant/releases/download/v0.8.0/air-canada-pack.zip\necho '74b36f1d5c7777ea9a3ee240e32f992483a3cd2c0dda0c7d065229c49f1a8249  air-canada-pack.zip' | shasum -a 256 -c\nunzip air-canada-pack.zip\nwarrant --store air-canada-pack/.warrants verify\nwarrant --store air-canada-pack/.warrants check b423b6a82c3451bfbd75563b39e6391093a64db57941d9247a61a6c620bd997f\n```\n\nThe last command re-executes the content-addressed, ATP-bounded reason locally;\nit does not merely read the filed verdict. The pinned asset, source specimen and\nportable layout are documented in [`demos/air-canada/`](demos/air-canada/),\n[`EVIDENCE-PACK.md`](EVIDENCE-PACK.md) and [`PUBLISHING.md`](PUBLISHING.md).\n\n## Integrate it\n\nAs a GitHub Actions gate:\n\n```yaml\n- uses: s0fractal/warrant@v0.6.0\n  with:\n    store: ./evidence-pack\n    version: '0.6.0'\n```\n\nPin `0.6.0` or newer for domain-separated signatures. The action checks the\nrequired capability, emits the machine report and fails on verification errors;\nsee [`action.yml`](action.yml).\n\nFrom an MCP client:\n\n<!-- mcp-name: io.github.s0fractal/warrant -->\n\n```bash\nwarrant-mcp-server --store /abs/path/.warrants\nclaude mcp add warrant -- warrant-mcp-server --store /abs/path/.warrants\n```\n\nThe server exposes filing, store verification and reason inspection with fresh\n`ski@v1` replay. It is deliberately distinct from `warrant-mcp`, the sealing\nproxy for somebody else's downstream MCP server. See\n[`integrations/mcp-server/`](integrations/mcp-server/) and\n[`integrations/mcp/`](integrations/mcp/).\n\n## Contract map\n\n| Surface | Authority |\n|---|---|\n| Record format, canonicalization, signatures, replay, settlement and trust config | [`SPEC.md`](SPEC.md) |\n| JSON schemas | [`schemas/`](schemas/) — derivative; SPEC remains normative |\n| Portable `.warrants/` bundle | [`EVIDENCE-PACK.md`](EVIDENCE-PACK.md) |\n| Writing WPL checks | [`docs/authoring-checks.md`](docs/authoring-checks.md) |\n| WPL design boundary | [`docs/policy-language-choice.md`](docs/policy-language-choice.md) |\n| Threat model | [`THREAT-MODEL.md`](THREAT-MODEL.md) |\n| External implementation contract | [`conformance/`](conformance/) |\n| Releases and artifacts | [`PUBLISHING.md`](PUBLISHING.md) and [`CHANGELOG.md`](CHANGELOG.md) |\n\nThe Python reference implements the five filing verbs and settlement. Go is an\nindependent verify/settle implementation. Rust is a from-scratch base-grade\nimplementation including Ed25519 verification. All three were produced within\none author/model lineage: agreement is conformance evidence, not independent\ncustody or adoption.\n\n```bash\npython3 impl/warrant.py conformance examples\npython3 impl/warrant.py selftest\n(cd impl-go && go build -o warrant-go .)\n./impl-go/warrant-go conformance examples\n(cd impl-rs && cargo build --release)\n./impl-rs/target/release/warrant-rs conformance examples\npython3 tests/differential.py\n```\n\nA fourth JavaScript candidate was created without Warrant implementation source\nand reached the complete base grade under a self-certified iterative local-model\nexperiment. Its settlement grade is unimplemented. This establishes bounded\nimplementability against that frozen corpus, not external custody, adoption or\ncorrectness beyond it; see [`needs/README.md`](needs/README.md).\n\nTo test another implementation without executing ours:\n\n```bash\npython3 conformance/run.py --candidate \"./your-verifier probe\"   # 139 vectors\npython3 conformance/run.py --candidate \"./your-verifier probe\" --self-check\n```\n\nThe runner checks the candidate's typed answer. 62\nof the 139 vectors are MUST-REJECT, and the pack reports `base` and `settlement`\nseparately. Details and digest verification are in\n[`conformance/README.md`](conformance/README.md).\n\n## Breaking signature boundary\n\nSince release `0.6.0`, signatures cover the domain-separated message\n\n```text\n\"warrant-sig-v1:\" || WarrantID_raw\n```\n\nrather than the bare WarrantID. There is no dual-accept window. Pre-0.6.0\nsignatures therefore do not verify under the current protocol. Where the old\nsigning key is available, migrate only signatures — WarrantIDs and body links do\nnot change:\n\n```bash\nwarrant resign --key mykey.key --dry-run\nwarrant resign --key mykey.key\n```\n\n## Settlement\n\nSettlement is a separate verification grade defined by SPEC §5.1, §7, §9 and\n§12. It derives key state and active roots from explicit trust configuration,\nreplays settlement-active reasons, and requires new evidence or a new outcome\nfingerprint to reopen a subject. Prose alone never reopens settlement.\n\n```bash\npython3 impl/warrant.py verify --settlement --trust-config trust.json\npython3 impl/warrant.py settle <settling-wid> candidate-body.json\n./impl-go/warrant-go verify --settlement --trust-config trust.json <store>\npython3 tests/settlement.py\n```\n\nAn unusable requested trust configuration fails closed; it does not fall back to\na clean base-grade report. `genesis.json` is advisory unless explicitly pinned\nby the verifier.\n\nThe only known format consumer is the sibling `sigma-glyph` repository. It is a\nworking same-author integration, not outside adoption. Published software,\nprotocol adoption, green CI, self-review and independent validation remain\ndifferent claims.\n\nLicense: MIT.\n",
  "bytes": 10097,
  "sha": "738dd17b1b8970e7cfcb0786c0c4e26bcee1e5d204e071e6470337130b04ef6b",
  "repo_slug": "s0fractal/warrant",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_s0fractal_warrant_12fa06c4/readme"
}