Performance improvements, better readme and complete python bindings

include/kpn/inode.hpp

@@ -0,0 +1,32 @@
+#pragma once
+#include "diagnostics.hpp"
+#include <functional>
+#include <string>
+#include <string_view>
+
+namespace kpn {
+
+// Called when a node's function throws. Return true to skip the failed
+// invocation and keep running, false to stop the node.
+using NodeErrorHandler = std::function<bool(std::string_view node_name, std::exception_ptr)>;
+
+// ── INode — type-erased interface for Network / watchdog ─────────────────────
+
+struct INode {
+    virtual ~INode()       = default;
+    virtual void start()   = 0;
+    virtual void stop()    = 0;
+    virtual bool running() const = 0;
+    virtual const NodeStats& stats() const = 0;
+    virtual NodeSnapshot node_snapshot(const std::string& name, double elapsed_s) const = 0;
+    virtual void set_name(std::string name) = 0;
+
+    // halt(): alias for stop() — immediate, discards in-flight work.
+    virtual void halt() { stop(); }
+
+    // shutdown(): graceful drain before stopping. Base implementation falls
+    // back to stop(). Network and StaticNetwork override with topo-ordered drain.
+    virtual void shutdown() { stop(); }
+};
+
+} // namespace kpn