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.