# Millrace Rust Roadmap

This repository tracks the Rust crate parity roadmap for the Python
`millrace-ai` runtime. The Python package remains the production reference; the
Rust crate owns the `millrace` CLI, typed contracts, and local
`millrace-agents/` workspace artifact boundary.

## Current Release Target

The current Rust release target is `0.5.2`, aligned to Python `v0.20.3` at
commit `c607c0c12ee91c5982f2808481ee5b818de12da9`, ported from the Rust
`0.5.1` parity baseline for Python `v0.20.1`.

The `0.5.2` release closes the Python `v0.20.1..v0.20.3` stabilization delta:

- Graph-declared repair routing sends unclassified runtime blockers to the
  compiled repair node while preserving explicit Blueprint repair routes.
- Invalid Recon handoffs route to planning repair while attempts remain and
  preserve probe/root lineage labels with persisted `recon_handoff_invalid`
  evidence.
- Compiler-owned model aliases add default `fast`/`standard`/`deep` alias
  bindings, workspace-local `model-aliases` CLI management, and mode-local
  alias profiles including packaged `efficient_learning_codex`.
- Runtime-effect operation registries, request-context provider/render-plan
  registries, and related compiler validation are packaged as baseline
  authority and consumed by runtime status/doctor/run-inspection surfaces.
- Refactor compatibility surfaces preserve runner normalization, workspace
  family adapters, and public contract/export behavior while extending docs and
  package evidence.
- Optional Python `millrace-web` `v0.20.3` package/version sync is recorded as
  unsupported-gap evidence for the existing Rust boundary.

## Active Parity Boundary

Rust parity is judged at the operator-visible boundary:

- CLI command names, output shape, and exit behavior
- `millrace-agents/` workspace layout
- headed Markdown task/spec/incident/learning request documents
- runtime JSON artifacts and run inspection output
- compiled-plan semantics, graph routing, and currentness diagnostics
- daemon locking, mailbox intake, watcher intake, pause/resume/stop/reload
- serial tick, daemon scheduling, runner request/result, learning, closure,
  recovery, and usage-governance behavior

Rust source layout may differ from Python as long as these contracts stay
compatible.

## Release Evidence

- `CHANGELOG.md` records release-facing changes.
- `docs/rust-port-roadmap.md` records the port campaign and parity target.
- `docs/source-package-map.md` records package include rules and ownership.
- `docs/runtime/` records Rust runtime contract notes for operator and
  maintainer surfaces.
- `tests/fixtures/cli_parity/auto_port_v0_20_3_parity_evidence.json` records
  the Python `v0.20.1..v0.20.3` stabilization evidence, Rust `0.5.2`
  metadata/version outcomes, full final-gate Builder command results,
  dirty-worktree publish dry-run and mounted-filesystem permission guard
  evidence, target-dir fallback package verification, and package/web-gap
  evidence for this pass.

## Explicit Gaps

Rust still does not ship a `millrace-web` package, HTTP dashboard, static shell,
SSE stream, or dashboard API route. The accepted Rust inspection surface
remains local read-only CLI commands over initialized workspaces, including
`millrace compile graph` and `millrace runs trace <run_id>` as graph/trace
shadow surfaces; the Python `v0.20.3` web package/version changes are recorded
as unsupported-gap evidence rather than a Rust web implementation.
Native
filesystem watcher integration, live subscription-quota
provider polling, and live Codex/Pi smoke runs remain preview-only or opt-in
surfaces.
