TopoExec

TopoExec is a C++20 graph runtime for deterministic, observable, and testable in-process dataflow execution.

Deterministic · Observable · Testable · Composable · CLI-first

TopoExec is for embedders who want explicit graph semantics without adopting a service framework. It validates graph structure, compiles execution regions, runs bounded local graphs, and exposes plan/render/metrics/trace/live-observe surfaces that make runtime behavior inspectable.

Project status: beta / pre-production. TopoExec has extensive local tests, validation, observability, packaging, and documentation gates, but it is not advertised as production-proven or deployed at scale.

Why TopoExec?

• Declarative graph specification with schema and semantic validation.
• Deterministic execution regions for local in-process runtime behavior.
• Rich trigger, async, channel, and CompositeLoop semantics beyond a simple task runner.
• Built-in plan/render, metrics, trace, diagnostics, and live observe tooling.
• Stable, smokeable examples designed for CI and golden-output checks.
• Small C++20-first core; adapters and ecosystem integrations stay behind clear boundaries.

Quick Start

cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build -j
./build/topoexec graph validate examples/00-getting-started/minimal.yaml
./build/topoexec graph plan examples/00-getting-started/minimal.yaml --format json
./build/topoexec graph render examples/00-getting-started/minimal.yaml --format mermaid
./build/topoexec graph run examples/00-getting-started/minimal.yaml --steps 1

Expected run summary:

ok
graph: minimal
ticks: 3
stop_reason: tick_bound
channel_publish_count: 2
channel_delivery_count: 2

Dependencies are CMake, a C++20 compiler, yaml-cpp, CLI11, nlohmann_json, and GTest for tests. If GTest is unavailable, the build fetches it through CMake FetchContent.

Visual Showcase

These images are generated from real example metadata and topoexec CLI output, not hand-maintained screenshots.

Example	What it shows
	The smallest source → transform → sink path for validate, plan, render, and run.
	any_input, all_inputs, time_sync, batch, rate_limit, debounce, and condition policies in one graph.
	Metrics, structured trace, Chrome trace, and live observe NDJSON from a real run.
	A declared estimator/controller feedback SCC with fixed-point loop policy.

Regenerate or check the gallery:

python3 scripts/update_examples_index.py --check
python3 scripts/render_example_assets.py --topoexec build/topoexec --check

Core Capabilities

Capability	What it means
Validation	Catch graph/config problems before runtime with schema and semantic checks.
Plan & render	Inspect compiled regions and topology as JSON or Mermaid/SVG assets.
Triggers	Express readiness/suppression with any_input, all_inputs, time_sync, batch, condition, debounce, and rate_limit.
Async	Model deferred completions with bounded queue capacity and max_inflight.
Composite loops	Declare controlled immediate feedback SCCs with convergence and budget policy.
Metrics & trace	Inspect runtime counters, structured trace events, Chrome trace, and live observe streams.
Testing support	Use deterministic JSON/text outputs, examples metadata, and focused gates in CI.

Example Gallery

Start at examples/README.md for the generated learning path.

Path	Purpose
examples/00-getting-started/	Minimal pipeline and first CLI commands.
examples/10-basic-dataflow/	Branching, fan-out, and merge/join behavior.
examples/20-triggers/	Trigger readiness and suppression policies.
examples/30-async/	Async worker edge with bounded inflight.
examples/40-composite-loop/	Declared iterative feedback loop.
examples/50-observability/	Metrics, trace, Chrome trace, and live observe output.
examples/60-testing-validation/	Clear validation diagnostics and golden-friendly output.
examples/70-performance/	Local benchmark smoke without cross-machine claims.
examples/80-realistic-mini-scenario/	Synthetic robot-cell-inspired mini pipeline.
examples/90-dogfood-pilot/	Synthetic dogfood pilot with metrics, trace, live assertions, and benchmark smoke.

Documentation

• First run: Getting started, Examples guide, Cookbook.
• Runtime semantics: Concepts, Runtime architecture, Runtime semantics, Semantic contract.
• Tooling: CLI reference, Live runtime validation, Metrics schema, Trace events.
• Embedding/API: API overview, Public API stability, Adapter boundaries.
• Maintenance: Testing strategy, Build and package, Contributing, Roadmap backlog.

Embedding

Pure C++ applications can link only the runtime target:

find_package(topoexec CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE topoexec::runtime)

Use GraphSpec directly or the convenience builder in topoexec/runtime/graph_builder.hpp. YAML loading and CLI tooling are optional through topoexec::yaml; dependency-free preview boundaries exist for adapters, C API, Python automation, and plugin loading.

Project Boundaries

TopoExec is a compact local runtime, not a distributed workflow platform. The following remain deferred, preview-only, or intentionally out of scope unless a future goal explicitly opens them:

• full GUI editor, LSP, or production dashboard platform;
• production ROS 2 package/client-library adapter;
• production OpenTelemetry or Prometheus exporters;
• native Python bindings, stable C ABI, or sandboxed plugin ecosystem;
• schema v2 migration tooling and external Perfetto adapter;
• hard real-time scheduling, affinity, preemption, or production timing claims.

graph observe is a local observability and test-validation surface. It is disabled by default at runtime, bounded when enabled, and does not provide runtime control, pause/resume/step, fault injection, remote multi-user access, or production telemetry export.

Contributing and License

See Contributing, the code of conduct, and the Apache-2.0 license.