{"id":49626498,"url":"https://github.com/sean2077/topoexec","last_synced_at":"2026-05-07T09:01:06.077Z","repository":{"id":354852705,"uuid":"1225598769","full_name":"sean2077/topoexec","owner":"sean2077","description":"C++20 single-process stateful dataflow runtime with graph validation, channel policy, CompositeLoop regions, and CLI tooling","archived":false,"fork":false,"pushed_at":"2026-05-06T08:42:00.000Z","size":1965,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T08:46:39.878Z","etag":null,"topics":["cmake","cpp","dataflow","graph-validation","runtime"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sean2077.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-30T12:51:58.000Z","updated_at":"2026-05-06T08:42:04.000Z","dependencies_parsed_at":null,"dependency_job_id":"cd68c50d-872d-4dc4-8fec-e8ba9147ff60","html_url":"https://github.com/sean2077/topoexec","commit_stats":null,"previous_names":["sean2077/topoexec"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/sean2077/topoexec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean2077%2Ftopoexec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean2077%2Ftopoexec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean2077%2Ftopoexec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean2077%2Ftopoexec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sean2077","download_url":"https://codeload.github.com/sean2077/topoexec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean2077%2Ftopoexec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32730282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-07T02:14:30.463Z","status":"ssl_error","status_checked_at":"2026-05-07T02:14:29.405Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cmake","cpp","dataflow","graph-validation","runtime"],"created_at":"2026-05-05T07:34:24.239Z","updated_at":"2026-05-07T09:01:06.052Z","avatar_url":"https://github.com/sean2077.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TopoExec\n\nTopoExec is a compact C++20 runtime for stateful in-process execution graphs. It gives applications explicit semantics for edge visibility, feedback loops, bounded channels, trigger readiness, payload ownership, metrics, and trace events without requiring a service framework.\n\nTopoExec is not a distributed runtime, ROS adapter, Python framework, GUI editor, or OpenTelemetry/Prometheus exporter. Those adapter surfaces are deferred until the core runtime API is stable.\n\n## Quickstart\n\n```bash\ncmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo\ncmake --build build -j\nctest --test-dir build --output-on-failure\n./build/topoexec_app_cpp_builder_minimal\n./build/topoexec graph run examples/minimal.yaml --steps 1\n```\n\nDependencies are CMake, a C++20 compiler, `yaml-cpp`, `CLI11`, `nlohmann_json`, and GTest for tests. If GTest is not installed, the build fetches it through CMake `FetchContent`.\n\n## Core Concepts\n\n- `Component`: user code with lifecycle hooks and one `execute()` / `execute_status()` entry point.\n- `GraphSpec`: declarative lanes, components, edges, and optional CompositeLoops.\n- Edge kinds: `immediate`, `delay`, `state`, and `async`.\n- Channel policy: latest, queue, barrier, previous-tick, overflow behavior, and copy policy.\n- Trigger policy: manual, any/all input, time sync, batch, request, and task-ready.\n- CompositeLoop: explicit owner for immediate feedback SCCs.\n\n```mermaid\nflowchart LR\n  ComponentRegistry --\u003e RuntimeRunner\n  GraphSpec --\u003e Validator --\u003e CompiledPlan\n  CompiledPlan --\u003e RuntimeRunner\n  RuntimeRunner --\u003e EventRuntime\n  EventRuntime --\u003e TriggerPolicy\n  EventRuntime --\u003e PublicationRouter\n  PublicationRouter --\u003e RuntimeChannels\n  RuntimeChannels --\u003e TriggerPolicy\n  EventRuntime --\u003e MetricsTrace[Metrics + Trace]\n```\n\n## Embedding\n\nPure C++ applications can link only the runtime target:\n\n```cmake\nfind_package(topoexec CONFIG REQUIRED)\ntarget_link_libraries(my_app PRIVATE topoexec::runtime)\n```\n\nBuild graphs directly in C++ with `GraphSpec` or `topoexec/runtime/graph_builder.hpp`. `examples/apps/cpp_builder_minimal` is the minimal embeddable example. YAML loading and CLI tooling are optional through `topoexec::yaml`.\n\n## CLI Tools\n\n```bash\ntopoexec graph validate examples/minimal.yaml\ntopoexec graph plan examples/composite_loop.yaml --format json\ntopoexec graph render examples/composite_loop.yaml --format mermaid\ntopoexec graph run examples/minimal.yaml --steps 1\ntopoexec graph run examples/minimal.yaml --steps 10 --until-idle\ntopoexec graph metrics examples/minimal.yaml --steps 1 --format json\ntopoexec graph trace examples/minimal.yaml --steps 1\ntopoexec graph trace examples/minimal.yaml --steps 1 --format chrome \u003e topoexec-trace.json\ntopoexec graph lint examples/control_feedback_delay.yaml\ntopoexec graph explain examples/minimal.yaml\ntopoexec graph diff-plan examples/minimal.yaml examples/control_feedback_delay.yaml\ntopoexec graph bench examples/minimal.yaml --steps 1 --runs 2\n```\n\nThe CLI validates `schema_version: 1` graphs, emits text/JSON/Mermaid views, runs demo graphs, prints metrics/trace events, and provides lightweight lint/explain/diff/bench output derived from the runtime contract.\n\n## Examples\n\n- `examples/apps/minimal_pipeline`: immediate source-transform-sink execution.\n- `examples/apps/overload_latest_vs_queue`: latest overwrite versus bounded queue behavior.\n- `examples/apps/control_feedback_delay`: feedback delayed to the next epoch.\n- `examples/apps/composite_loop_fixed_point`: explicit immediate feedback owner.\n- `examples/apps/async_worker`: async deferred delivery, bounded queue behavior, and overload semantics.\n- `examples/apps/cpp_builder_minimal`: pure C++ graph builder path.\n\nEach app directory includes a README with graph shape, run command, expected output, semantic lesson, and contrast case.\n\n## Documentation\n\n- [Runtime semantics](docs/runtime-semantics.md)\n- [Schema v1](docs/schema-v1.md)\n- [API overview](docs/api-overview.md)\n- [Public API stability](docs/public-api.md)\n- [Payloads and ownership](docs/payloads.md)\n- [Scheduler semantics](docs/scheduler.md)\n- [Concurrency](docs/concurrency.md)\n- [Metrics](docs/metrics.md)\n- [Trace events](docs/trace-events.md)\n- [Performance baselines](docs/performance-baselines.md)\n- [FAQ](docs/faq.md)\n- [Adapter boundaries](docs/adapters.md)\n\nRelease planning is tracked in [CHANGELOG.md](CHANGELOG.md), [docs/versioning.md](docs/versioning.md), and [docs/release-checklist.md](docs/release-checklist.md). The current target is `v0.1.0-alpha`.\n\n## Known Limitations\n\n- `thread_pool` lanes support a bounded MVP for ready invocations, but priority, affinity, RT policy, persistent worker naming, and timeout-based preemption are advisory or not implemented.\n- Async `policy.max_inflight` admission is implemented for `async` edges; it is an admission limit for deferred completions, not a general async task/future executor.\n- Non-blocking ThreadSanitizer CI is wired for GitHub Actions; local `scripts/agent_check.sh` remains the required agent gate.\n- ROS 2, OpenTelemetry, Prometheus, Python, and external Perfetto adapters are deferred.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsean2077%2Ftopoexec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsean2077%2Ftopoexec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsean2077%2Ftopoexec/lists"}