Moving Verlato from Python to Rust¶
Verlato has moved to Rust, and the Python implementation is retired. The verlato crate
(crates/verlato) owns everything: the release-note pipeline with the IntentumDiff engine linked
in-process, every model provider (Ollama, LiteLLM/OpenAI-compatible endpoints, GitHub Models, the
external-command plugin, the Codex CLI and Claude Code agents, mock, stub and fallback chains),
commit intent inference and Conventional Commit drafting, every suggestion strategy (single,
paired, full-diff-json and tool-retrieval with Ollama tool calling) with adaptive
recommendations, the maintenance commands, the editor service and the MCP server
(verlato serve). Nothing is delegated to Python any more.
The verlato Python package is now a thin wrapper over that runtime: PyO3 bindings
(crates/verlato-python, the verlato._native extension module) plus a few lines of Python
(python/verlato). See The Python package. This document records the
assessment, how the port was checked, and the result.
Why Rust¶
- One engine, no Python at runtime for the core path. IntentumDiff's engine is Rust
(
intentumdiff-core); the Python package is a thin ctypes binding over it. Linkingintentumdiff_rust_core::api::review_sourcesdirectly removes the Python interpreter, pydantic model construction and the per-call FFI/JSON round trip from every file review. - Speed. Measured on this repository (
draft jsonover three commits, 80 changed files, no cache): 8.5 s native vs 29 s Python (Python already using four worker processes), with identical verdicts, group counts and symbol findings. The native pipeline reviews the files of each commit on parallel threads instead of spawning interpreter processes. - Distribution. The VS Code extension can ship a single executable plus the parser bundle
(
bin/verlato+wasm/) instead of requiring a Python 3.12 virtual environment. - One language with the engine. Engine API changes surface as compile errors instead of runtime attribute errors.
Assessment of the Python codebase¶
About 16k lines of Python (plus ~7k lines of tests):
| Area | Python modules | Lines | Status |
|---|---|---|---|
| Pipeline core: git collection, grouping, conventional commits, areas, checksums, evidence, deterministic classification, reconciliation | core/{collector,adapters,grouper,conventional,areas,checksum,diff_evidence,classifier (deterministic path),reconciler} |
~1.9k | Ported |
| IntentumDiff semantic evidence (digest, verdicts, summary, cache) | core/semantic.py |
~1k | Ported (engine linked natively) |
| Drafts, rendering, changelog apply, state store, review/feedback/state commands | core/{drafts,generator,changelog}, state/store.py, parts of cli/main.py |
~1.5k | Ported |
| Editor stdio service (deterministic methods) | service_stdio.py, parts of mcp/service.py |
~0.5k | Ported |
| Model providers: stub, mock, Ollama (incl. streaming), LiteLLM, GitHub Models, plugin, Codex/Claude CLI, fallback chains; request audits, privacy records, OTEL-style model logs | providers/*, core/model_privacy.py |
~2.4k | Ported (including Ollama tool calling) |
| Classifier model assists (summary rewrite, diff-fallback classification, change-summary payload) | parts of core/classifier.py, core/change_summary.py |
~0.6k | Ported |
Suggestions: prompt preview, --preview/--preflight for every strategy (single, paired, full-diff-json, tool-retrieval), batch fallbacks, applying a suggestion, the suggestion cache, scoring, adaptive recommendations, traces |
cli/main.py (parts), state/suggestion_cache.py, core/change_summary.py, core/suggestion_tools.py |
~4.5k | Ported |
| Commit intent inference and Conventional Commit drafting | core/commit_intent.py |
~1.1k | Ported |
Maintenance: doctor ollama, doctor model, model-logs export, feedback export, feedback recommend, state clear-suggestion-cache; the suggestion.* and state.clear_suggestion_cache service methods |
cli/main.py (parts), service_stdio.py, mcp/service.py |
~1k | Ported |
MCP server (verlato serve): FastMCP's handshake, tool/resource/prompt catalog, argument validation and result shapes; the MCP evidence tools (SuggestionEvidenceToolProvider) |
mcp/server.py, mcp/service.py, core/suggestion_tools.py |
~1.7k | Ported |
| GitHub API PR adapter | github/adapter.py |
~0.1k | Ported |
The CLI/service JSON contract is the migration seam: the VS Code extension only talks to
verlato <command> (JSON on stdout, progress on stderr) and to verlato service (JSON lines),
so the Rust binary replaces the Python one command by command without extension changes.
What runs where today¶
The native binary handles these command paths itself:
scan | generate | reconcile (with any model provider; see below)
draft json | preview | apply | review (including --model-provider)
draft prompt
draft suggest --preview | --preflight (every strategy; see below)
draft suggest --id (applies a model summary to review state)
commit conventional
render
state show | mark-published | clear-working | clear-suggestion-cache
feedback record | export | recommend
model-logs export
doctor engine | ollama | model
service (every method: health, info, draft.* incl. model providers and intent
inference, commit.conventional[_many], feedback.record, state.*,
suggestion.*)
serve (MCP server on stdio; all tools, resources and prompts)
Every command and service method runs natively. An unknown command is a usage error (exit code
2, as Python's argparse), an unknown service method answers invalid_request, and a PR adapter
that fails to configure is a plain error.
The maintenance commands print Python's exact bytes (including \uXXXX escapes and key order).
doctor ollama probes the configured Ollama with the same requests (warmup, single and two
concurrent probes), reads /api/ps and ollama ps, and reports the same bottleneck analysis;
doctor model sends the same full-diff-json probe (prompt, evidence and response schema) to any
provider. Suggestion cache backends: Python's register_suggestion_cache_backend only works
inside the registering interpreter, so a CLI or service process has just json, and both
runtimes report Unknown suggestion cache backend '<name>'; available: json for any other name
(suggestion_cache::open_backend is the one place to add a native backend; previews and
clear-suggestion-cache both use it).
scan/generate/reconcile (and drafts or reviews with --model-provider) ask the provider
to enrich summaries and, on the diff-fallback path, classifications. This runs natively for every
provider, with the same prompts, evidence payloads, request audits and hashes, [verlato:model]
trace lines and VERLATO_MODEL_LOG_PATH records as Python. The parity suite checks it with a
recording plugin, fake Ollama (plain and streaming), OpenAI-compatible and GitHub Models servers,
fake Codex/Claude executables, and the deterministic mock provider (which reproduces Python's
Mersenne Twister). The github PR adapter (VERLATO_PR_ADAPTER=github with VERLATO_GITHUB_REPO
and GITHUB_TOKEN/GH_TOKEN; VERLATO_GITHUB_API_URL for GitHub Enterprise) is native too.
Commit intent inference (--infer-commit-intents, VERLATO_COMMIT_INTENT_INFERENCE, or
"commit_intent_inference": "low-signal" in config) is native for every command that collects
groups and for the draft.* service methods: it derives a Conventional Commit from each commit's
diff (task derive-conventional, with the same fan-out guard, privacy downgrade, progress events
and request audits), uses the derived type/scope for low-signal commits when grouping and
classifying, and reports derived_conventional_commits on items. commit conventional and the
commit.conventional/commit.conventional_many service methods draft messages natively in both
evidence modes (diff-only, subject-hint).
draft suggest --preview/--preflight runs natively for every strategy: single; paired and
full-diff-json batches (batch prompts and JSON response schema, per-item and whole-batch
fallback to single calls, the 80k-character full-diff guard, --batch-size, parallel chunks and
the batch counters in performance); and tool-retrieval, where Ollama calls the suggestion
evidence tools (verlato_get_suggestion_item, the IntentumDiff semantic-diff tools, or bounded
patches with the git engine) for up to four rounds with the same tool-call trace lines and
tool metadata. --adaptive-recommendations (also doctor ollama) is native. draft suggest --id without
--preview (asks the provider for one summary and records it as an edited, model-generated summary
with provenance and a suggestion_applied feedback event) is native too. The parity suite compares outputs, cache files,
recorded model requests and trace lines against Python for both engines, a recording plugin and a
fake Ollama server (including tool calls and tool errors). Under IntentumDiff the structured
strategies embed engine-derived fields (version, sizes) in their prompts, so prompt hashes and
cache keys legitimately differ between the runtimes there; the suite masks only those.
The Python package¶
The verlato-core PyPI package (pyproject.toml, built with maturin; it installs the verlato command and module) holds:
verlato._native(crates/verlato-python): a PyO3 extension module, built for the stable ABI (abi3-py312: one wheel per platform for CPython 3.12+). It exposesrun(argv), which runsverlato::cli::runin-process without the GIL and returns the exit code;call(method, params_json, repo), which answers one service request throughverlato::service::call(the same dispatch asverlato service);version()andengine_version().python/verlato:verlato.run,verlato.call(parses the response, raisingServiceErroron an error answer),verlato.engine_version,verlato.parser_bundle,__version__, theverlatoandverlato-mcpconsole scripts (verlato-mcpisverlato serve) andpython -m verlato.verlato/wasm: the IntentumDiff parser bundle, provisioned at build time. Before running a command the wrapper setsVERLATO_INTENTUMDIFF_WASM_DIRto it unless that orINTENTUMDIFF_WASM_DIRis already set, so the package has no runtime dependencies.
The command line never exits the process: verlato::cli::run prints clap's usage errors and
--help/--version and returns clap's exit code, prints command errors and returns 1, and
flushes stdout and stderr before returning. The console scripts restore the default Ctrl-C
handler before running, because a command running without the GIL cannot see Python's
KeyboardInterrupt.
Versions: [workspace.package] version in Cargo.toml is the only version. Both crates inherit
it and pyproject.toml declares dynamic = ["version"], so maturin writes it into the wheel.
Engine and parser bundle¶
crates/verlato depends on intentumdiff-core pinned to a commit (see Cargo.toml) and calls
the supported api::review_sources per changed file. Each commit is reviewed as
parent..sha: changed paths from git diff --raw, both blob versions from one
git cat-file --batch, files reviewed in parallel. Files the engine cannot review are recorded
as unreviewed with the engine's reason; a failing file never fails the commit. Digests use the
same JSON format as the Python implementation and are cached in .verlato_semantic_cache.json
(cache keys include the engine build, so the two runtimes do not share entries).
The engine loads its language parsers (WebAssembly components) from a parser bundle:
parser_manifest.json plus *.wasm. The runtime looks in VERLATO_INTENTUMDIFF_WASM_DIR,
INTENTUMDIFF_WASM_DIR, then wasm/ next to the executable. The Python package and the release
bundles ship it (verlato/wasm in the wheel, wasm/ beside the executable in a bundle).
Provision it with:
scripts/fetch_intentumdiff_parsers.sh # -> target/release/wasm
scripts/fetch_intentumdiff_parsers.sh python/verlato/wasm # for the Python package
The script is the bundle's single pinned source. It extracts the components from the
checksum-pinned intentumdiff-python 0.0.3b1 wheel on PyPI (the components are platform
independent), checks that every component the manifest names is present, and checks each
against a SHA-256 recorded in the manifest when there is one (0.0.3b1's manifest records none).
The wheel is built from intentumdiff-core 1c4bdbc5, the revision Cargo.toml pins.
The pin must move together with the intentumdiff-core revision in Cargo.toml: the
parsers are built for that engine. When IntentumDiff publishes native releases with a standalone
parser bundle, the script should switch to that artifact.
Parity¶
tests/test_rust_parity.py builds repositories with conventional commits, PR merges, area
splits, docs/test-only changes, formatting-only edits, added/removed functions and breaking
markers, and runs every command, the stdio service and the MCP server against them, comparing
with the Python implementation: identical JSON, Markdown, changelog and state files, model
requests, traces and telemetry (with --diff-engine git exactly; with IntentumDiff, ignoring
only engine build identity).
The Python implementation is retired, so its side of every comparison is replayed from
recordings in tests/golden/parity, made from the last commit that had it (see
tests/golden/README.md): each Python invocation's exit code, stdout, stderr, the files it
changed, the requests fake servers received from it and its MCP traffic. The native side runs
live, through the installed Python package (python -m verlato) or the executable in
VERLATO_RUST_BIN. A replay fails if a test asks anything that was not recorded.
Known, intentional differences:
- JSON output escapes: Python writes
\uXXXXfor non-ASCII characters, Rust writes UTF-8. Both parse to the same values. health/infoservice responses add"runtime": "rust"(andinforeports the parser bundle).- Cross-file move detection (
semantic_cross_file) runs natively through the engine's commit index (since IntentumDiff 0.0.3); it is opt-in and off by default, as in Python, and the parity scenarios leave it off.
A changelog re-apply bug found while porting (re-applying a version left that version's old subsections behind) was fixed in both implementations.
Upstream IntentumDiff issues¶
Engine gaps found while building on IntentumDiff. IntentumDiff 0.0.3 (core 1c4bdbc5) fixed all
of them, and Verlato dropped the workarounds it carried. Both runtimes were changed the same
way before the goldens were re-recorded.
| Issue | Gap | Status in Verlato |
|---|---|---|
| core#297 | No definition-level signature change; a new required parameter was only an identifier addition |
Removed. Signatures come from the engine's REFACTORING/CHANGE_SIGNATURE change. Its definition facts (param_count, default_count) decide whether the required-parameter count grew. A change is extended (compatible) only when the old parameter list is an exact prefix of the new one and every new parameter can be omitted, a check made on the definition's source text. Signature changes are behavioural, not refactorings, even though the engine files them under REFACTORING. |
| core#298 | One file over the fuel budget failed cross-file analysis for the whole commit | Removed. The engine's commit index skips files it can't index and reports them in index_errors; Verlato records them as excluded from cross-file index: …. |
| core#299 | Spurious MOVED_CODE for the surviving sub-expression of a modified statement |
Removed (the move folding). The engine folds the sub-expression into the modification. |
| core#300 | Change descriptions didn't say what changed (text_diff empty) |
Removed for modifications. A modified statement carries the engine's bounded old -> new text instead of Verlato's before/after snippets. Kept for added and deleted definitions: the engine still describes those only by kind and name (Insert -> function_definition('handle')), so their bounded source text stays (after for an addition, before for a deletion). |
| core#301 | Files over ~10k lines failed fixed size limits | Fixed upstream as configurable limits. A file over the limits is recorded as unreviewed with kind too_large; semantic_max_nodes raises the limits. |
| core#250 | Spurious module pseudo-moves from duplicate names |
Fixed upstream. The remaining part, the synthetic module. prefix on top-level names and root modules taking part in move matching, moved to core#311 (0.0.4): Verlato strips the prefix and drops module-kind entries until then. |
| python#332 | finalize_commit_diff crashed on FileDiffError results |
Not applicable. The native engine calls the core's commit index directly. |
Gaps found while upgrading to 0.0.3, filed for 0.0.4:
| Issue | Gap | Verlato workaround |
|---|---|---|
| core#330 | Added and deleted definitions are described only by kind and name, with no source text | Keeps its bounded before/after snippets for added and deleted definitions |
| core#331 | api::review_sources returns size-limit failures as a plain ReviewError::Engine |
Recognises them by message text to record too_large and point at semantic_max_nodes |
| core#332 | CHANGE_SIGNATURE's fact_delta reports only param_count, and param_count counts Python's bare * |
Reads the parameter list from source to decide whether a change is extended. A bare * is handled like other * entries, so the inflated count cancels out |
IntentumDiff 0.0.3 also reports whether a review explains the whole change (core #252). A file
whose review is incomplete is recorded as unreviewed (kind incomplete) with the engine's
message, never as a clean review.
LLM evidence¶
Model-backed features consume the IntentumDiff semantic diff instead of raw patches (see "What
the LLM sees" in the README). The semantic diff lives in the per-commit digest
(FileSemantics.changes, digest format v2), which the Rust engine produces in the format the
Python implementation used.
Remaining phases¶
- Providers (done): the
Providertrait, request/prompt/evidence hashes (byte-identical canonical JSON), privacy records, every provider, fallback chains, model telemetry and the classifier's model assists. - Suggestions (done):
draft prompt,draft suggest --preview/--preflightfor every strategy (single, paired, full-diff-json, tool-retrieval with Ollama tool calling), the suggestion cache, adaptive recommendations, and applying a suggestion to review state (draft suggest --id). - Commit intents (done): inference for grouping/classification and Conventional Commit
drafting (
commit conventional,commit.*service methods). - MCP server (done):
verlato servespeaks newline-delimited JSON-RPC on stdio without an MCP SDK. The tool/resource/prompt catalog is FastMCP's own output, embedded incrates/verlato/src/mcp_catalog.json(it was FastMCP's output from the Python server; edit it by hand now, and the parity suite fails on drift from the recorded catalog), and the legacy patch tools are listed only with thegitengine. Arguments are validated against the catalog schemas with pydantic's lax coercions and error messages. Known differences: the stateless2026-07-28protocol is not offered (clients negotiate2025-11-25), requests are answered one at a time, and pydantic messages are reproduced only for the schema shapes the catalog uses. The GitHub adapter is done. - Retire Python (done): delegation is removed, the Python implementation is deleted (its
answers are kept as golden recordings), and the
verlatoPython package is a thin PyO3 wrapper that ships the native runtime and parser bundle. Releases (rab, see Releasing) publish the wheels and sdist to PyPI and per-platform native bundles (executable +wasm/) to GitHub Releases, which the VS Code extension can use.
Each phase moved commands from "delegated" to "native" behind the same CLI contract and extended the parity suite before the Python code for them was deleted.
Building¶
cargo build --release -p verlato # links the IntentumDiff engine (first build ~6 min)
scripts/fetch_intentumdiff_parsers.sh # parser bundle next to the binary
cargo test --workspace # unit tests
scripts/fetch_intentumdiff_parsers.sh python/verlato/wasm
maturin develop --release # the Python package, into the active virtualenv
pytest # package tests and parity (golden replay)
cargo build -p verlato --no-default-features builds without the engine (only
--diff-engine git works) for fast iteration on the pipeline.