RFC: Rust SDK production parity — governed data plane, workflow enforcement, and native integrations

## Summary

Propose a coordinated roadmap to make the Rust SDK a first-class, production-ready governance data plane for Agent Governance Toolkit (AGT).

This is an umbrella and sequencing RFC. It does not replace existing feature, defect, dependency, or cross-language parity trackers. Those issues remain authoritative for their scope and should be linked as child work. New child issues should be opened only for gaps that are not already tracked.

The intended outcome is not a line-for-line port of every Python package. Python can remain the broad reference and control-plane ecosystem, while Rust provides semantically equivalent enforcement, security, audit, and integration capabilities for performance-sensitive Rust applications.

## Motivation

The Rust SDK has advanced substantially since the initial crate proposal in #556 and the feature matrix introduced by #943. It now includes policy evaluation, identity and trust, tamper-evident audit, MCP security, prompt-injection controls, execution controls, sandboxing, credential support, command-line operations, and telemetry foundations.

The remaining work is spread across several trackers and is difficult for maintainers and adopters to assess as one coherent production-readiness story. In particular:

- workflow-level governance remains incomplete;
- framework support is largely generic rather than demonstrated through concrete Rust ecosystem integrations;
- operational persistence and observability need a defined completion bar;
- Rust performance is plausible but is not yet established through a maintained benchmark baseline; and
- there is no explicit adoption criterion showing that a consuming Rust application can use the published crate in continuous integration.

Without an umbrella contract, there is a risk of duplicating existing trackers, treating interface presence as end-to-end enforcement, or declaring parity without behavioural and operational evidence.

## Definition of parity

For this roadmap, parity means:

1. **Semantic parity** — equivalent policy inputs produce compatible decisions and wire values across Python and Rust.
2. **Security parity** — equivalent fail-closed behaviour, action binding, timeout handling, provenance, and auditability at enforcement boundaries.
3. **Operational parity** — supported persistence, diagnostics, telemetry, packaging, and upgrade behaviour for production deployments.
4. **Integration parity** — concrete, runnable integrations for important Rust-native frameworks and protocols, rather than adapter-shaped types alone.
5. **Measured performance** — reproducible latency, throughput, footprint, and regression evidence on a documented reference environment.
6. **Adoption evidence** — at least one maintained consumer exercises the published Rust crate and its governance path in continuous integration.

Parity does not require the Rust SDK to reproduce language-agnostic dashboards, marketplaces, discovery services, or every Python-only framework adapter.

## Relationship to existing work

This RFC coordinates the following work; it does not supersede it:

| Existing item | Relationship to this roadmap |
|---|---|
| #556 | Historical foundation for the Rust SDK; closed and not reopened by this RFC |
| #943 | Historical SDK feature matrix; useful baseline, but now needs a source-backed refresh |
| #3083 | Authoritative cross-language tracker for approval-chain execution |
| #3084 and #3450 | Authoritative tracker and in-flight implementation for accumulated-context governance |
| #2986 | Authoritative cross-language tracker for skill-aware audit hardening where concrete adapters exist |
| #3521 | Known Rust normalization correctness/parity defect |
| #3355 and #3420 | Dependency modernization issue and in-flight implementation |
| #2573 | Transparent proxy parity; remains dependency-gated on #3081, #3082, and the Python implementation |
| #2445 and #2446 | Completed foundations for command-line support and telemetry; follow-up breadth is tracked here only where not already implemented |

Before opening any child issue from this RFC, contributors should search both open and closed issues and link the result in the child issue.

## Proposed roadmap

The expected delivery shape is approximately 12 focused PRs for semantic and integration parity, followed by up to four operational-completeness PRs. Exact boundaries should be adjusted during review to keep each change independently testable and reviewable.

### Phase 1 — Capability contract and measurement

1. **Living Rust capability manifest and parity matrix**
- Replace snapshot-style capability claims with a source-backed manifest.
- Mark capabilities as `shipped`, `partial`, `missing`, `blocked`, or `deferred`.
- Link each entry to implementation, tests, specifications, issues, and known limitations.
- Distinguish API presence from enforcement and production-readiness.

2. **Rust governance benchmark suite**
- Add maintained benchmarks for policy and ACS evaluation, prompt normalization and detection, MCP gateway operations, and audit append/verification.
- Add accumulated-context benchmarks after #3450 lands.
- Publish the toolchain, features, workload, reference hardware, latency/throughput results, and binary-size measurements with each baseline.
- Keep shared-runner results informational until a stable reference runner and variance policy are agreed.

### Phase 2 — Close known correctness and in-flight work

3. Complete and merge #3450 rather than creating a competing accumulated-context implementation.
4. Fix #3521 and add shared Python/Rust vectors for nesting-order symmetry and transform tags.
5. Complete #3420, remove resulting deprecation warnings, and verify the supported Rust version and package gates.

### Phase 3 — Workflow governance

6. Add the Rust action-bound approval request, entry, and resolution contracts required by ADR 0030 and #3083.
7. Add ordered approval coordination with webhook support, short-circuit deny, cancellation, expiry, and fail-closed timeout behaviour.
8. Add durable human suspension/resumption and an optional LLM advisory adapter. LLM output must not independently create an approval resolution.

Approval work must use the existing #3083 contract and shared conformance vectors rather than defining a Rust-specific protocol.

### Phase 4 — Rust-native adoption paths

9. Add an optional asynchronous integration surface with explicit cancellation and timeout semantics while preserving the synchronous core and existing default features.
10. Add a real Tower `Layer`/`Service` integration covering input, pre-tool, post-tool, output, and usage-reporting boundaries.
11. Add a real Rig integration with a runnable governed agent/tool example.
12. Integrate with the official MCP Rust SDK and provide governed server/client examples without duplicating the canonical `agentmesh-mcp` crate.

Concrete integrations must incorporate the trusted framework-owned metadata, deterministic context hashing, UTC-normalized timestamps, and spoof-resistance requirements tracked by #2986.

### Phase 5 — Operational completeness

These may require up to four additional PRs after the earlier contracts settle:

- governance for memory/context writes and retrieval;
- pluggable durable state with at least one documented production backend;
- broader metrics and tracing across policy, trust, audit, prompt defence, MCP, and execution controls; and
- operator verification commands plus a maintained consuming application or reference deployment running against the published crate in continuous integration.

Transparent proxy work from #2573 is intentionally not scheduled in these phases. It should enter the roadmap only after its prerequisite contracts are accepted and the shared implementation is available.

## Security implications

This roadmap expands the Rust enforcement surface, so the following constraints apply to all child work:

- governance failures, unavailable approval backends, expired approvals, cancellation, and unmeasurable security state fail closed;
- approvals are bound to the exact action and policy/configuration versions and cannot be replayed across requests;
- untrusted request content cannot supply trusted framework identity, provenance, or approval identity;
- security-relevant state transitions are auditable without recording secrets or unnecessarily sensitive payloads;
- policy evaluation remains deterministic and outside model-controlled decision loops;
- asynchronous and framework dependencies remain feature-gated where practical, preserving a small default dependency and attack surface;
- the canonical MCP crate boundary is retained; integrations adapt it rather than copy it; and
- benchmark claims describe the tested workload and environment and are not presented as universal production guarantees.

Any child issue that changes a public security contract should receive its own focused design review.

## Migration and backward compatibility

- Existing synchronous APIs and default feature sets should remain compatible wherever possible.
- New runtime and framework integrations should be opt-in features until their stability and dependency cost are understood.
- Shared wire values and serialized records require cross-language conformance tests before release.
- Necessary breaking changes must include an explicit migration path and follow the repository's versioning policy.
- Existing issues and pull requests should be completed or amended; parallel replacement implementations should not be opened without maintainer agreement.

## Non-goals

- Port every Python package or integration into Rust.
- Move language-agnostic control-plane services into the Rust SDK.
- Introduce an unconditional asynchronous runtime dependency.
- Reimplement the transparent proxy before #2573 is unblocked.
- Create another MCP implementation beside the canonical Rust MCP crate.
- Turn noisy shared CI benchmark results into a blocking performance gate without an agreed baseline and variance policy.

## Acceptance criteria

The roadmap is complete when:

- [ ] A maintained capability manifest accurately describes Rust support and limitations.
- [ ] Shared Python/Rust conformance vectors cover policy decisions, approval records, accumulated context, normalization, and audit wire values.
- [ ] #3083 and the Rust portion of #3084 are complete, including fail-closed runtime enforcement rather than data types alone.
- [ ] Known Rust-specific security and correctness parity defects, including #3521, are resolved or explicitly accepted with documented rationale.
- [ ] Concrete Tower, Rig, and official MCP SDK examples exercise complete governance boundaries.
- [ ] Trusted integration metadata and audit hardening satisfy the applicable requirements in #2986.
- [ ] Reproducible performance baselines are published for the critical governance paths.
- [ ] Rust formatting, linting, tests, documentation tests, package checks, and dependency/security checks pass for supported feature combinations.
- [ ] Operational documentation covers configuration, failure modes, timeouts, persistence, telemetry, and upgrades.
- [ ] At least one maintained consuming Rust application or reference deployment uses the published crate and exercises its governance path in continuous integration.
- [ ] Each child issue and PR links back to this RFC, and the capability manifest is updated as work lands.

## Alternatives considered

### Literal Python feature-for-feature parity

Rejected. It would duplicate language-agnostic services and low-value Python-specific integrations while obscuring the Rust SDK's intended role as a native enforcement and runtime layer.

### Continue with independent feature issues only

Rejected. Existing issues are useful implementation units but do not provide a shared completion definition, dependency order, performance baseline, or adoption criterion.

### Declare parity from API/module presence

Rejected. A type or adapter interface does not prove fail-closed enforcement, cross-language semantics, operational readiness, or usability by a real consumer.

### Use a sidecar as the only Rust integration

Rejected as the sole path. A sidecar remains valuable for zero-code and cross-language deployments, but it does not replace a native low-latency SDK for Rust applications.

## Prior art and references

- Initial Rust SDK proposal: #556
- SDK feature matrix: #943
- Approval protocol: ADR 0030 and #3083
- Accumulated context: #3084 and #3450
- Cross-language integration audit hardening: #2986
- Transparent proxy tracker: #2573
- Tower `Service`: https://docs.rs/tower/latest/tower/trait.Service.html
- Rig: https://docs.rig.rs/
- Official MCP Rust SDK: https://github.com/modelcontextprotocol/rust-sdk
- Tokio: https://tokio.rs/tokio/tutorial
- Criterion.rs: https://bheisler.github.io/criterion.rs/book/

## Checklist

- [x] I searched open and closed issues and RFCs for a Rust production-parity or equivalent umbrella roadmap.
- [x] I reviewed the ADR index and the related approval, proxy, accumulated-context, audit-hardening, dependency, and correctness work.
- [x] This proposal links and preserves existing trackers rather than replacing them.
- [x] I am willing to help refine the decomposition and contribute implementation work.

## Coordination status

This is an umbrella RFC, so it has no single implementation PR. Existing child issues and in-flight PRs listed above remain authoritative for their scopes. Any new child issue or PR should reference #3680 and the applicable existing tracker rather than create a parallel roadmap.

Start by reviewing the linked trackers, especially #3083, #3450, #3521, and #2986, then search open and closed issues before proposing a child issue. Choose one focused roadmap gap with explicit tests and conformance evidence; completion should satisfy that child issue's acceptance criteria and update the capability manifest.

Written by the indexing model from the issue text.