docs/runtime.md

Runtime

The local asynchronous runtime resolves WorkflowIR references, schedules independent DAG nodes concurrently, and returns per-node timing metrics and sink outputs.

Before any handler runs, it verifies workflow and reference integrity, captures the exact registered handler and trusted ToolContract, and evaluates policy and approval. The single RuntimeDispatcher.dispatch boundary rechecks the binding and authorization, validates arguments, asks an optional asynchronous RuntimeGuard, invokes that exact handler, then validates its output. A registry swap between preflight and invocation is rejected. The order is deliberate: Trace2MCP policy cannot be weakened by the external guard, and the guard sees the final validated arguments and trusted contract metadata.

The guard is absent by default. When configured, allow continues, while deny and require_approval stop execution. Guard exceptions and invalid decisions also stop execution. The built-in HOL Guard adapter uses its CLI hook in a separate process and never imports its internal Python modules.

Supported nested calls (registry.get, registry.invoke, or invoke_capability) return through the same dispatcher. They require an explicitly reviewed contract; a handler cannot create or expand the run's immutable approval set. Unknown capabilities and unsupported schema keywords fail closed.

Concurrency is bounded. Timeouts are enforced. Retries are allowed only for trusted, idempotent, safe operations. When one async node fails, sibling tasks are cancelled and awaited.

The runtime is in-process. It is not a sandbox, distributed engine, durable queue, transaction coordinator, or compensation system. Synchronous handler code cannot be forcibly cancelled by Python once it has started.