Major refactor: scheduling, shared event loop, CLI extraction, observability

[lukastk]

Summary

Implements the full refactor plan in _dev/refactor_plan.md, Phases 0-5. Touches the execution model, scheduling, pool internals, the CLI, and documentation.

Phase 0 — Bug fixes + observability hooks

• ExecutionManager.run() now cleans up _worker_jobs in finally so timeouts/cancellation don't leak stale entries.
• _async_worker_func._handle_run always emits a terminal event — uncaught user exceptions no longer hang the manager.
• netrun validate no longer silently swallows resolution failures.
• faulthandler.register(SIGUSR1, all_threads=True) at Net start; gc.collect() + RSS delta tracking between retries.

Phase 1 — Shared event loop

• Single asyncio loop per process (daemon thread) replaces per-worker loops. Workers submit coroutines via run_coroutine_threadsafe().
• Auto-detects sync vs async from the function signature; sync nodes still run directly on the worker.
• Subprocesses, nested awaits, cross-node asyncio.Lock all just work — no more nest_asyncio workarounds.

Phase 2 — Scheduling constraints + retry state

• ctx.state: per-epoch mutable dict that persists across retries. Cache expensive precomputation so retries don't redo it.
• NodeExecutionConfig.depends_on: list[str]: directional ordering without data edges. Cycles and unknown nodes raise ValueError at Net construction.
• NodeExecutionConfig.resources: dict[str, int] + NetConfig.resources: named semaphores. Replaces the heavy-pool workaround for mutual exclusion / bounded concurrency / GPU scheduling.

Phase 3 — Pool/RPC/EM cleanup

• Extracted BasePool for shared pool lifecycle.
• Removed dead protocol weight: send_channel parameter, UP_RUN_STARTED (merged into UP_RUN_RESPONSE), UP_PRINT_BUFFER, NetProtocolKeys enum.
• Worker crash isolation — a crashed worker only fails its own jobs.
• Validate depends_on for cycles + invalid references.

Phase 4 — Config cleanup

• Removed unused config fields, consolidated epoch state.

Phase 5 — CLI extraction + new commands

• CLI extracted to a separate netrun-cli package at the repo root. Same nblite workflow as netrun. The netrun script is now installed via netrun-cli's [project.scripts]. The netrun package no longer ships a CLI or cli extras group.
• New CLI features:
  • netrun node <name> --edges — show incoming/outgoing edges for a node.
  • netrun structure --format=mermaid — emit a Mermaid topology diagram (renders in GitHub, VSCode, etc.).
  • netrun dry-run — show topological execution order, source/sink nodes, pool assignments, and scheduling constraints (no node code runs).

Documentation audit

• Rewrote CLAUDE.md (repo root) for: separated netrun-cli package, scheduling constraints, ctx.state, shared event loop, worker crash isolation, removed protocol elements.
• Updated README.md (repo root) and netrun/README.md for the same.
• Refreshed inline docstrings on ExecutionManager, Net, and NodeExecutionContext.
• Deleted stale netrun/PROJECT_SPEC.md references.
• Added 3 focused sample projects under sample_projects/:
  • 15_ctx_state — retry-persistent caching with ctx.state.
  • 16_depends_on — three nodes with no data edges, ordering enforced by depends_on.
  • 17_resources — three jobs serialized through a 1-slot resource on a 3-worker thread pool (proves serialization via wall-clock timing).

Stats

• 92 files changed, +15,846 / -3,128.
• 13 commits, each self-contained per the refactor plan's PR sequence.

Test plan

• cd netrun && uv run pytest src/tests/ -q — all 1,305 tests pass
• cd netrun-cli && uv run pytest src/tests/ -q — all 61 tests pass (50 inherited + 11 new for --edges, --format=mermaid, dry-run)
• Sample 14 (14_web_scraping_pipeline) — comprehensive showcase using all new features
• Samples 15/16/17 — focused demos, each verified to run with expected output (e.g. sample 17 reports ~0.6s wall-clock for serialised jobs, not ~0.2s)
• Smoke test new CLI features against sample_projects/00_basic_net_project

Migration notes

For downstream consumers:

• Required: replace netrun[cli] extras with a separate netrun-cli dependency.
• Optional but recommended: replace 1-worker "heavy" pool patterns with resources={"name": 1}; replace ad-hoc retry caches (module-level vars, threading.local) with ctx.state; remove nest_asyncio.apply() workarounds.
• No migration needed: Net, NetConfig, NodeExecutionContext, factory protocol, on_epoch_* callbacks, run_until_blocked, output queues, structured logging — all unchanged.

🤖 Generated with Claude Code