corvus-rust-runtime

name	corvus-rust-runtime
description	Corvus-specific Rust runtime guidance. Trigger: When working in clients/agent-runtime on providers, channels, tools, security, memory, gateway, runtime adapters, or other trait-driven runtime boundaries.
license	Apache-2.0
metadata	{"author":"generic-author","version":"1.0"}

Corvus Rust Runtime

Repo-specific guidance for clients/agent-runtime. Load this together with the base rust skill when changes depend on Corvus architecture, security boundaries, runtime contracts, or validation commands.

When to Use

• Any change under clients/agent-runtime/src/**
• Adding a provider, channel, tool, memory backend, observer, or runtime adapter
• Touching security/, gateway/, auth/, tools/, or memory/
• Wiring implementations in a factory mod.rs
• Reviewing Rust changes for repo fit, safety, and validation scope

Critical Patterns

Think in extension points first

Corvus is trait-driven. Before creating a new abstraction, check the existing contracts.

Capability	Contract	Usual location
Provider	src/providers/traits.rs	src/providers/*.rs
Channel	src/channels/traits.rs	src/channels/*.rs
Tool	src/tools/traits.rs	src/tools/*.rs
Memory	src/memory/traits.rs	src/memory/*.rs
Observer	src/observability/traits.rs	src/observability/*.rs
Runtime adapter	src/runtime/traits.rs	src/runtime/*.rs

See references/runtime-architecture.md.

Security is a default, not an add-on

For security/, gateway/, auth/, and tools/:

• fail closed
• validate inputs at the boundary
• never log secrets or raw tokens
• never widen access or policy scope silently

See references/security-boundaries.md.

Repo-specific engineering constraints

• No unwrap() / expect() in production paths unless failure is truly impossible
• Prefer minimal dependencies; binary size matters
• Keep patches local and focused
• Avoid blocking work in async paths
• Preserve CLI/API contracts unless intentionally changing them
• Add regression tests first for bugs when practical

Validation by risk

Run the smallest relevant checks before calling work done.

See references/validation-commands.md.

Decision Table

Change	Preferred move
New integration type already matches a trait	implement trait + register in mod.rs
Security/policy uncertainty	deny/fail closed
Cross-module behavior change	add integration or regression test
Heavy new dependency	challenge it before adding
Runtime hot path touched	verify async/blocking/clone impact

Code Examples

Register in the right factory

pub fn register_tools(registry: &mut ToolRegistry) {
    registry.register("my_tool", std::sync::Arc::new(MyTool::new()));
}

Return typed runtime errors

#[derive(Debug, thiserror::Error)]
pub enum ToolError {
    #[error("input validation failed: {reason}")]
    InvalidInput { reason: String },
}

Commands

make rust-fmt
make rust-clippy
make rust-test

cargo test --manifest-path clients/agent-runtime/Cargo.toml
cargo clippy --manifest-path clients/agent-runtime/Cargo.toml --all-targets -- -D warnings

Resources

• References: see references/
• Assets: see assets/ for Corvus starter templates