{"id":37665527,"url":"https://github.com/runtimeverification/mir-semantics","last_synced_at":"2026-04-12T00:27:53.530Z","repository":{"id":149367720,"uuid":"515635295","full_name":"runtimeverification/mir-semantics","owner":"runtimeverification","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-26T12:07:14.000Z","size":19100,"stargazers_count":37,"open_issues_count":77,"forks_count":4,"subscribers_count":17,"default_branch":"master","last_synced_at":"2026-02-26T12:57:38.654Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/runtimeverification.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-07-19T15:11:49.000Z","updated_at":"2026-02-25T19:28:21.000Z","dependencies_parsed_at":"2025-12-19T15:09:20.576Z","dependency_job_id":null,"html_url":"https://github.com/runtimeverification/mir-semantics","commit_stats":null,"previous_names":[],"tags_count":353,"template":false,"template_full_name":null,"purl":"pkg:github/runtimeverification/mir-semantics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runtimeverification%2Fmir-semantics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runtimeverification%2Fmir-semantics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runtimeverification%2Fmir-semantics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runtimeverification%2Fmir-semantics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/runtimeverification","download_url":"https://codeload.github.com/runtimeverification/mir-semantics/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/runtimeverification%2Fmir-semantics/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29993603,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-16T11:58:22.004Z","updated_at":"2026-04-12T00:27:53.520Z","avatar_url":"https://github.com/runtimeverification.png","language":"Python","funding_links":[],"categories":["Verifiers"],"sub_categories":[],"readme":"# MIR Semantics\n\n`mir-semantics` models the semantics of Rust Stable MIR in K. The repository also ships `kmir`, a Python CLI for building the semantics, running programs, generating specs, and inspecting proofs.\n\nFor semantics details and specialized workflows, see [Further Reading](#further-reading).\n\n## Quick Start\n\n### Prerequisites\n\n- [Python](https://www.python.org/) `\u003e= 3.10`\n- [`uv`](https://docs.astral.sh/uv/)\n- [`pip`](https://pip.pypa.io/) `\u003e= 20.0.2`\n- [`gcc`](https://gcc.gnu.org/) `\u003e= 11.4.0`\n- [Rust](https://rustup.rs/) via `rustup`\n- [K Framework](https://github.com/runtimeverification/k?tab=readme-ov-file#quick-start), using the version pinned in [`deps/k_release`](deps/k_release)\n\n### Clone and set up\n\n```bash\ngit clone --recurse-submodules https://github.com/runtimeverification/mir-semantics.git\ncd mir-semantics\n\n# If you cloned without --recurse-submodules:\ngit submodule update --init --recursive\n```\n\n### Build\n\nThe pinned Rust toolchain and components are declared in [`rust-toolchain.toml`](rust-toolchain.toml) and installed automatically by `rustup` on first use.\n\n```bash\n# Build K semantics definitions (required for kmir)\nmake build\n\n# Build stable-mir-json (required for SMIR generation, integration tests)\nmake stable-mir-json\n```\n\n`uv` will create and use the Python environment for the `kmir` project automatically.\n\n### Verify the setup\n\n```bash\n# Just kmir\nuv --project kmir run kmir --help\n\n# Full contributor check\nmake smir-parse-tests\n```\n\n## Common Workflows\n\n### Task-to-command map\n\n| Task | Command | Notes |\n| --- | --- | --- |\n| Build the semantics | `make build` | Requires K and the Python prerequisites. |\n| Build `stable-mir-json` in-tree | `make stable-mir-json` | Requires initialized submodules and the pinned Rust nightly. |\n| Run unit tests | `make test-unit` | Python-only tests under `kmir/src/tests/unit`. |\n| Run integration tests | `make test-integration` | Depends on `stable-mir-json` and `build`. |\n| Check Stable MIR parsing | `make smir-parse-tests` | Compiles Rust test programs to SMIR JSON and parses them with `kmir`. |\n\n`make test-integration` already depends on `make stable-mir-json` and `make build`, so it is the full contributor path for integration coverage.\n\n## Using `kmir`\n\nEvery subcommand supports `--help` for the full option list.\n\n| Command | Purpose |\n| --- | --- |\n| `kmir run` | Execute a Rust program from SMIR JSON |\n| `kmir prove` | Prove properties of a Rust source file (recommended entry point) |\n| `kmir show` | Inspect a proof graph — nodes, deltas, rules, statistics |\n| `kmir view` | Interactive proof viewer |\n| `kmir prune` | Remove a node (and its subtree) from a proof |\n| `kmir section-edge` | Split a proof edge into finer sections |\n| `kmir link` | Link multiple SMIR JSON files into one |\n| `kmir info` | Show type information from a SMIR JSON file |\n\n### Typical proof workflow\n\n```bash\n# 1. Run a proof\nuv --project kmir run kmir prove program.rs --proof-dir ./proofs --verbose\n\n# 2. Overview — see all leaves and statistics\nuv --project kmir run kmir show proof_id --proof-dir ./proofs --leaves --statistics\n\n# 3. Zoom into specific nodes / transitions\nuv --project kmir run kmir show proof_id --proof-dir ./proofs --nodes \"4,5\" --node-deltas \"4:5\"\n\n# 4. See which K rules fired on an edge\nuv --project kmir run kmir show proof_id --proof-dir ./proofs --rules \"4:5\"\n\n# 5. Full detail for deep debugging\nuv --project kmir run kmir show proof_id --proof-dir ./proofs --nodes \"5\" \\\n    --full-printer --no-omit-static-info --no-omit-current-body\n```\n\n### Debugging a stuck or failing proof\n\nWhen a proof does not close, the typical cycle is **inspect → refine → re-prove**:\n\n```bash\n# Narrow down where things go wrong — break on every function call\nuv --project kmir run kmir prove program.rs --proof-dir ./proofs \\\n    --break-on-calls --max-depth 200\n\n# Or break only when a specific function is entered\nuv --project kmir run kmir prove program.rs --proof-dir ./proofs \\\n    --break-on-function \"my_module::suspect_fn\"\n\n# Split a large edge to find the exact divergence point\nuv --project kmir run kmir section-edge proof_id \"4,5\" --proof-dir ./proofs --sections 4\n\n# Prune a bad subtree and re-run\nuv --project kmir run kmir prune proof_id 5 --proof-dir ./proofs\nuv --project kmir run kmir prove program.rs --proof-dir ./proofs\n\n# Export a proof subgraph as a reusable K module\nuv --project kmir run kmir show proof_id --proof-dir ./proofs --to-module lemma.json --minimize-proof\n# then re-prove with the lemma\nuv --project kmir run kmir prove program.rs --proof-dir ./proofs --add-module lemma.json\n```\n\nOther useful `prove` break flags: `--break-every-step`, `--break-every-terminator`, `--break-on-thunk`, `--terminate-on-thunk`.\n\n### Generate Stable MIR JSON manually\n\nAfter `make stable-mir-json`:\n\n```bash\n# Single file\ndeps/.stable-mir-json/debug.sh -Zno-codegen your_file.rs\n\n# Cargo project\nRUSTC=deps/.stable-mir-json/debug.sh cargo build\n\n# Convenience script (also supports png/pdf/dot visualization)\n./scripts/generate-smir-json.sh \u003crust-file\u003e \u003coutput-dir\u003e [png|pdf|dot]\n```\n\n## Troubleshooting\n\n- **Rust toolchain errors**: The toolchain is declared in [`rust-toolchain.toml`](rust-toolchain.toml) and should install automatically on first use. If not, run `rustup toolchain install nightly-2024-11-29 --component llvm-tools --component rustc-dev --component rust-src`.\n- **`deps/stable-mir-json` is missing**: Run `git submodule update --init --recursive`.\n- **Not sure which `make` target to run**: `make build` for basic `kmir`; add `make stable-mir-json` for SMIR generation; `make test-integration` for the full suite.\n\n## Further Reading\n\n- [docs/semantics-of-mir.md](docs/semantics-of-mir.md)\n- [docs/example-mir-execution-flow.md](docs/example-mir-execution-flow.md)\n- [docs/dev/adding-intrinsics.md](docs/dev/adding-intrinsics.md)\n- [docs/feature-checklist.md](docs/feature-checklist.md)\n- [Stable-MIR-JSON repository](https://github.com/runtimeverification/stable-mir-json/)\n\n## Supporters\n\nKMIR / mir-semantics is supported by funding from:\n- [Polkadot Open Gov](https://polkadot.subsquare.io/referenda/749)\n- Solana\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruntimeverification%2Fmir-semantics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fruntimeverification%2Fmir-semantics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fruntimeverification%2Fmir-semantics/lists"}