Find the header. Keep the result.
Applications link one CMake target, include the narrowest direct header, and branch on the domain's typed result. Diagnostic text never becomes a second status protocol.
One link target
find_package(runD 1.0.4 EXACT CONFIG REQUIRED)
target_link_libraries(your_app PRIVATE runD::sdk)Consumers do not link Kernel, Accel, Node, Metal, or Vulkan implementation targets directly. The installed SDK owns their correct composition.
Direct headers by task
Include these entries directly. Headers staged only as transitive support are not additional application entry points.
| Task | Direct entry | Start here |
|---|---|---|
| Flow, Program, Job, Batch, targets | <rund/compute.hpp> | Compute |
| Asynchronous Flow compilation | <rund/compute/async.hpp> | Compute |
| Composite Compute math and matrix stages | <rund/compute/math.hpp> | Numerics |
| Dependent resident Programs | <rund/compute/pipeline.hpp> | Compute |
| Submit Job/Pipeline through Session | <rund/compute/session.hpp> | Runtime |
| Canonical Record, Replay, Scenario | <rund/replay.hpp> | Replay |
| Session lifecycle and telemetry | <rund/session.hpp> | Runtime |
| Cooperative tasks and channels | <rund/task.hpp> | Runtime |
| Host observations and logical time | <rund/host.hpp> | Runtime |
| Socket ownership and asynchronous byte I/O | <rund/net.hpp> | Runtime |
| Hierarchical storage budget | <rund/storage.hpp> | Runtime |
| Numeric-policy identity and encoding | <rund/evidence.hpp> | Numerics |
All rund domains in one translation unit | <rund/rund.hpp> | This page |
| 32-bit deterministic vector math | <math32/math32.hpp> | Numerics |
| 64-bit deterministic vector math | <math64/math64.hpp> | Numerics |
| Optional placement and retry identity | <cluster/cluster.hpp> | Runtime |
compute::Fixed<I,F> comes from <rund/compute.hpp>.
Telemetry configuration and events come through <rund/session.hpp>.
Choose CMake visibility from your C++ boundary
# runD appears only in this target's implementation.
target_link_libraries(engine PRIVATE runD::sdk)
# A public engine header exposes runD values or templates.
target_link_libraries(engine_sdk PUBLIC runD::sdk)
PUBLIC propagates the same exact SDK, C++20 requirement, numeric compile policy,
headers, and link closure. It does not expose a second runD target. Keep runD names out of
public headers when you want an implementation-only dependency.
Result and failure ownership
Expensive or fallible boundaries return typed outcomes. A failure cannot be mistaken for an empty valid output. Branch on its code/reason, show the derived text, and return its process exit code unchanged.
auto result = flow.collect();
if (!result) {
const std::string_view message = result.error();
std::fprintf(stderr, "runD failure (code=%u): %.*s\n",
static_cast<unsigned>(result.code()),
static_cast<int>(message.size()), message.data());
return result.exit_code();
}| Domain | Typed authority | Use it for |
|---|---|---|
| Compute | compute::Reason / compute::Code | Selection, admission, compile, allocation, execution, readback, Batch, and Pipeline failures. |
| Replay | replay::Code | Input, schema, Record, Scenario, checkpoint, history, persistence, and comparison failures. |
| Runtime, Task, Host, Network, Storage | rund::ReasonCode | Lifecycle, scheduling, storage, readiness, transport, and host-observation failures. |
| Application assertion | Process exit 2 | A value mismatch only after all product outcomes succeeded. |
Common actions
| Class | Action |
|---|---|
| Unsupported | Choose an operation or policy inside the documented implementation contract. |
| Unavailable | Check device/runtime state and the exact platform dependency tuple. |
| Invalid input or shape | Fix the exact type, count, schema, order, or lifetime before retrying. |
| Capacity or budget | Change the declared bound or reduce the workload; runD does not silently clamp. |
| Execution/device | Preserve target, SDK tuple, code, graph/output evidence, and minimal reproduction. |
1.0.4 is an Alpha surface
The installed direct-header set and current result contracts are checked for this release. Compatibility may still change before a stable version. Always use exact package discovery, the version-matched docs, and the release's verified artifact tuple.
Source-private Kernel, Accel, and direct Node headers are never consumer entry points. For exact current declarations, inspect the installed headers or the optional direct-header registry ↗.