Zachery Aaron Shores-Chmielewski
b887e941cb
Introduce the swactor engine: a swactor-owned composite that retains a selected execution substrate, drives the core runtime, and hosts the async/blocking/timer work that backs actors. Integrations receive one cloneable EngineHandle and never construct or borrow a raw Tokio runtime/handle. Engine crate (crates/engine): - The contract: spawn / spawn_blocking / timer / interval / now, a per-implementation capability model with construction-time binding (require()), and engine-owned time. The engine owns all progression; actor handlers stay synchronous and never .await. - TokioBackend owns the Tokio runtime and schedules core ticks and supporting futures on it; SteppingBackend is a single-threaded deterministic scheduler with virtual time (the non-Tokio portability proof). Core is driven through its existing tick() surface; a self-rescheduling CoreDriver is installed at construction and is the sole place permitted to call try_tick. iroh-driver: - Receives an EngineHandle instead of a raw Tokio Handle. Accepts, reads, dials, writes, endpoint construction, and teardown schedule through it; required capabilities (tasks/timers/io) are validated before the endpoint binds. Engine-hosted interval pumps drive actor-bridge, datastream, and edge ingress. myelin: - One node/orchestrator engine owns core, protocol tick injection, and transport progression; the application loop only drains integration-owned queues. Stage-shard process readers, delayed actor messages, helper stdout/stderr, prompt RPC, and CPU sampling all schedule through the engine (spawn_blocking / engine tasks / timers). - Removed the split-engine APIs: install_actor_bridge_pump(period) and spawn_protocol_ticker(period) use each component's stored engine; deleted the no-op pump_network callback and its plumbing; deleted the dashboard raw-Tokio/standalone-runtime conveniences. Enforcement: - A clippy disallowed-methods boundary forbids direct runtime/scheduling/ time/core-driving bypasses, denied in swactor-engine, iroh-driver, and myelin. Retained excluded uses (VastAI provider, provider process supervision/log capture, OS-signal/stdin/process-control sequencing) carry narrow allowances with reasons. Verification: - Engine contract + unit tests (incl. the SteppingBackend portability proof), iroh integration tests (capability rejection before binding, multi-node actor behavior), and a production execution-composition smoke test that observes engine-driven actor progress with no ambient Tokio runtime and no manual tick/pump. Workspace all-target/all-feature clippy and tests are green. Specs co-located with their crates: ENGINE_SPEC.md in crates/engine, IROH_DRIVER_SPEC.md in crates/iroh-driver. VastAI remains explicitly out of scope pending its separate redesign.
52 lines
4 KiB
TOML
52 lines
4 KiB
TOML
# Clippy enforcement policy for the swactor engine boundary
|
|
# (ENGINE_SPEC.md §2 / §3.1).
|
|
#
|
|
# These direct runtime / scheduling / time / core-driving operations are
|
|
# disallowed outside the engine's own substrate implementation. Integrations
|
|
# (iroh-driver, myelin, ...) must go through `EngineHandle`. The
|
|
# `swactor-engine` Tokio backend and the core driver carry narrow
|
|
# `#[allow(clippy::disallowed_methods)]` exemptions because they ARE the
|
|
# substrate implementor; the VastAI provider module carries a temporary
|
|
# module-level exemption pending its separate redesign (out of scope per §2).
|
|
#
|
|
# In-scope work that backs actors, transport, RPC, sampling, or node/orchestrator
|
|
# progression must schedule through `EngineHandle`. The only retained direct
|
|
# uses are narrow exclusions (§2): provider adapters/lifecycle (VastAI),
|
|
# provider-specific process supervision and log capture, and top-level OS-signal
|
|
# / blocking user-stdin / synchronous process-control sequencing. Each retained
|
|
# use carries a local `#[allow]` with its exclusion reason.
|
|
#
|
|
# Workspace-wide enforcement: `swactor-engine`, `iroh-driver`, and in-scope
|
|
# `myelin` carry `#![deny(clippy::disallowed_methods)]` and pass clean.
|
|
|
|
disallowed-methods = [
|
|
{ path = "tokio::runtime::Runtime::new", reason = "runtime ownership belongs to the engine; construct an engine-owned substrate instead" },
|
|
{ path = "tokio::runtime::Builder::new_current_thread", reason = "runtime ownership belongs to the engine; use EngineHandle" },
|
|
{ path = "tokio::runtime::Builder::new_multi_thread", reason = "runtime ownership belongs to the engine; use EngineHandle" },
|
|
{ path = "tokio::runtime::Handle::current", reason = "ambient runtime detection is forbidden; construct an engine-owned substrate instead" },
|
|
{ path = "tokio::runtime::Handle::try_current", reason = "ambient runtime detection is forbidden; construct an engine-owned substrate instead" },
|
|
{ path = "tokio::runtime::Runtime::block_on", reason = "blocking on a runtime is forbidden; schedule through EngineHandle" },
|
|
{ path = "tokio::runtime::Handle::block_on", reason = "blocking on a runtime is forbidden; schedule through EngineHandle" },
|
|
|
|
{ path = "tokio::spawn", reason = "direct scheduling is forbidden; use EngineHandle::spawn" },
|
|
{ path = "tokio::task::spawn", reason = "direct scheduling is forbidden; use EngineHandle::spawn" },
|
|
{ path = "tokio::task::spawn_blocking", reason = "use EngineHandle::spawn_blocking" },
|
|
{ path = "tokio::runtime::Runtime::spawn", reason = "direct scheduling is forbidden; use EngineHandle::spawn" },
|
|
{ path = "tokio::runtime::Handle::spawn", reason = "direct scheduling is forbidden; use EngineHandle::spawn" },
|
|
{ path = "tokio::runtime::Runtime::spawn_blocking", reason = "use EngineHandle::spawn_blocking" },
|
|
{ path = "tokio::runtime::Handle::spawn_blocking", reason = "use EngineHandle::spawn_blocking" },
|
|
|
|
{ path = "tokio::time::sleep", reason = "use EngineHandle::timer" },
|
|
{ path = "tokio::time::sleep_until", reason = "use EngineHandle::timer" },
|
|
{ path = "tokio::time::interval", reason = "use EngineHandle::interval" },
|
|
{ path = "tokio::time::interval_at", reason = "use EngineHandle::interval" },
|
|
{ path = "tokio::time::timeout", reason = "use an engine-derived timeout" },
|
|
{ path = "tokio::time::timeout_at", reason = "use an engine-derived timeout" },
|
|
|
|
{ path = "std::thread::spawn", reason = "direct thread scheduling is forbidden; schedule through EngineHandle" },
|
|
{ path = "std::thread::sleep", reason = "use EngineHandle::timer; retained only for narrow process-control exclusions (ENGINE_SPEC.md §2)" },
|
|
|
|
{ path = "swactor::runtime::Runtime::tick", reason = "manual core driving is forbidden; the engine owns core progression" },
|
|
{ path = "swactor::runtime::Runtime::try_tick", reason = "manual core driving is forbidden; the engine owns core progression" },
|
|
{ path = "swactor::runtime::Runtime::has_work", reason = "manual core driving is forbidden; the engine owns core progression" },
|
|
]
|