duroxide copilot-instructions.md

Duroxide AI Agent Instructions

A durable execution runtime for Rust. Key docs: docs/ORCHESTRATION-GUIDE.md, docs/provider-implementation-guide.md.

⚠️ CRITICAL: Git Operations

NEVER commit or push without explicit user permission. Always ask before running git commit or git push.

⚠️ CRITICAL: Test Execution

ALWAYS use nextest for running tests. This is mandatory - nextest provides faster execution and better output.

cargo nt                              # Run all tests (nextest alias)
cargo nt -E 'test(/pattern/)'         # Filter tests by pattern
cargo nt --test specific_test_file    # Run specific test file

Only fall back to cargo test if nextest is not available. Never use cargo test when cargo nt works.

Architecture Overview

Two-queue message-driven runtime:

• OrchestrationDispatcher (orchestrator queue): Processes workflow turns, durable timers, and external events
• WorkDispatcher (worker queue): Executes activities with automatic lock renewal for long-running work

Core types:

• OrchestrationContext - Schedules work via schedule_activity(), schedule_timer(), schedule_wait(), schedule_sub_orchestration() - all return futures you can .await directly
• Event/Action - Immutable history entries; providers only store, never generate IDs
• Provider trait - Storage abstraction with peek-lock semantics (src/providers/mod.rs)

Critical Patterns

Awaiting schedule_ methods:*

// schedule_* methods return futures that can be awaited directly
let result = ctx.schedule_activity("Task", input).await?;
ctx.schedule_timer(Duration::from_secs(5)).await;
let event_data = ctx.schedule_wait("MyEvent").await;
let sub_result = ctx.schedule_sub_orchestration("Child", input).await?;

Use ctx.join/select, NOT tokio::join/select:

// ✅ CORRECT - deterministic, history-ordered resolution
match ctx.select2(timer, activity).await {
    Either2::First(()) => { /* timer won */ }
    Either2::Second(result) => { /* activity won */ }
}
let results = ctx.join(vec![f1, f2, f3]).await;

// ❌ WRONG - non-deterministic, breaks replay
let (a, b) = tokio::join!(f1, f2);  // NEVER use tokio::join in orchestrations!
tokio::select! { ... }              // NEVER use tokio::select in orchestrations!