# bijux-dag-runtime
[](https://crates.io/crates/bijux-dag-runtime)
[](https://docs.rs/bijux-dag-runtime)
[](https://github.com/bijux/bijux-core/blob/main/LICENSE)
[](https://github.com/bijux/bijux-core/actions/workflows/ci.yml?query=branch%3Amain)
[](https://github.com/bijux/bijux-core)
[](https://bijux.io/bijux-core/) [](https://bijux.io/bijux-core/bijux-dag/packages/bijux-dag-runtime/)
`bijux-dag-runtime` is the execution engine for `bijux-dag`. It handles
runtime planning, scheduling, adapter invocation boundaries, policy checks,
replay classification, cache behavior, and trace emission.
`bijux-dag` v0.4.1 is a local-first DAG runtime for reproducible workflows
with explicit graph contracts, deterministic execution records, verified
artifacts, cache explanation, and replayable run bundles. This crate is the
runtime layer that executes, records, replays, and verifies that promise.
## Release Status
- public crate on the `v0.4.1` DAG release line
- execution-time layer for the local-first controller
- stable local, Kubernetes Job, and shared-filesystem SLURM execution lanes
- modeled remote-worker and generic scheduler contracts that remain outside
the public operator promise
## What It Provides
- execution planning and node orchestration
- policy evaluation and runtime diagnostics
- replay, diff, cache, and artifact integration behavior
- local shell and local container execution
- Kubernetes Job execution for container nodes through `kubectl` and a shared
persistent volume claim
- SLURM submission through `sbatch`, terminal-state polling through `sacct`,
and result collection from a shared run directory
- versioned external-adapter handshakes for repository-integrated executors
- container engine detection, mounted input and output layout, stdout/stderr
capture, and retained container identity
- branch pruning, skipped-lane recording, trigger-rule evaluation, and replay
equivalence over selected execution paths
Use this crate when you need to execute validated DAG graphs, replay retained
runs, enforce runtime policy, or integrate with Bijux execution behavior from
Rust.
## What It Does Not Own
- authoritative graph schema and validation rules
- top-level command parsing or output presentation
- release-governance and maintainer report composition
## Good Fit
- executing validated graphs from Rust
- replaying or comparing retained runs
- integrating with cache, adapter, and runtime policy behavior
- consuming the same execution semantics that power `bijux-dag`
## Runtime Identity Rules
- runtime manifests and provenance records stamp the crate package version
directly from build metadata
- an optional Git short SHA may be appended at build time when the crate is
compiled from a repository checkout or injected through
`BIJUX_DAG_BUILD_GIT_SHA` for release-tree builds
- runtime execution does not shell out to `git` to discover version identity
- replay and cache identity therefore do not depend on the operator's current
working directory or any unrelated Git repository around the binary
Use these rules when reviewing runtime fingerprint drift or provenance output.
## Integration Boundaries
| external adapters | descriptor handshake, explicit execution paths, typed failure information, and adapter-binary identity in cache evidence | [Adapter Contract](https://github.com/bijux/bijux-core/blob/main/docs/spec/ADAPTER_CONTRACT.md) |
| Kubernetes | container nodes submitted as Jobs, shared-volume workspace mapping, resource and deadline mapping, pod-state mapping, logs, and retained batch evidence | [Batch Execution Model](https://github.com/bijux/bijux-core/blob/main/docs/spec/BATCH_EXECUTION_MODEL.md) |
| SLURM | shared-filesystem jobs submitted with `sbatch`, polled with `sacct`, and collected into the retained node result | [Batch Execution Model](https://github.com/bijux/bijux-core/blob/main/docs/spec/BATCH_EXECUTION_MODEL.md) |
| retained lifecycle evidence | terminal status, validated lifecycle transitions, per-attempt output, and bounded log summaries | [Run Evidence Layout](https://bijux.io/bijux-core/bijux-dag/interfaces/run-evidence-layout/) |
| subprocess cleanup | process-group termination on Unix and explicit best-effort behavior on other hosts | [Execution Security And Isolation](https://bijux.io/bijux-core/bijux-dag/operations/security-isolation-truth/) |
| replay and cache | identity-aware reuse, refusal evidence, and replay verification | [Reproducibility Model](https://bijux.io/bijux-core/bijux-dag/interfaces/reproducibility-model/) |
These boundaries are observable contracts, not claims of host isolation.
Shell execution is not a VM boundary. Kubernetes and SLURM support is bounded
by the documented shared-storage contracts; it does not imply a public remote
worker service, generic HPC abstraction, or durable scheduler control plane.
## Backend Selection
The application layer selects the backend through `run --backend` and supplies
backend-specific configuration. This crate owns execution after that selection.
| `local` | shell and local-container nodes | host process or configured container engine | no VM or syscall isolation |
| `kubernetes` | container nodes | `kubectl`, a shared persistent volume claim, and a host/cluster path mapping | no general Kubernetes workflow controller |
| `slurm` | nodes executable by the configured worker command | `sbatch`, `sacct`, and a run directory visible to controller and worker | no support for arbitrary HPC storage or scheduler semantics |
The controller remains authoritative for accepted run state and retained
evidence in all three lanes. Scheduler status is input to that state machine,
not a replacement for it. Controller restart recovery is not currently part
of the batch-lane promise.
## Public Rust Surface
- browse docs.rs through `bijux_dag_runtime::stable` for the long-lived
runtime compatibility lane
- use `bijux_dag_runtime::prelude` for common planning and execution workflows
- use focused crate-root imports only when you already know the exact runtime
item you need
- use `bijux_dag_runtime::simulated_platform` only for deliberate modeled-platform
and control-plane evidence work
- Kubernetes and SLURM runtime configuration is available in the stable lane;
backend-heavy compatibility helpers remain callable for repository-owned
support work but stay hidden from the primary docs.rs lane
- use lane-scoped command discovery in `bijux-dag-app` or `bijux-dag-cli`
when you need to inspect experimental, simulated, or internal runtime
surfaces without widening the default operator contract
## Source Layout
- `src/runtime_core`: planning, execution, governance, and state transitions
- `src/adapters`: built-in and external adapter boundaries
- `src/backend/runtime`: local, container, Kubernetes, SLURM, and batch
execution
- `src/backend/distributed`: modeled coordination and remote-worker contracts,
not stable operator services
- `src/artifacts`, `src/cache`, `src/replay`, `src/policy`: core runtime
behavior around persisted evidence and reuse
- `src/diagnostics`: runtime-facing diagnostic helpers
## Reach For Another Crate When
- you need deterministic graph truth before runtime side effects:
`bijux-dag-core`
- you need command routing or output shaping:
`bijux-dag-app`
- you need only persisted artifact helpers without execution policy:
`bijux-dag-artifacts`
## Verify A Runtime Claim
| container inputs, outputs, and engine identity | [Container Packaging Workflow](https://bijux.io/bijux-core/bijux-dag/operations/container-packaging-workflow/) |
| Kubernetes and shared-filesystem SLURM support boundary | [Execution Mode Responsibilities](https://bijux.io/bijux-core/bijux-dag/architecture/execution-mode-responsibilities/) |
| cache reuse, invalidation, corruption refusal, and miss explanation | [Cache Behavior Workflow](https://bijux.io/bijux-core/bijux-dag/operations/cache-behavior-workflow/) |
| graph, execution, cache, and replay identity | [Reproducibility Model](https://bijux.io/bijux-core/bijux-dag/interfaces/reproducibility-model/) |
| branch selection, skipped lanes, and replay stability | [Branching Bulletin Workflow](https://bijux.io/bijux-core/bijux-dag/operations/branching-bulletin-workflow/) |
| retry evidence and focused replay repair | [Compliance-Gated Bulletin Workflow](https://bijux.io/bijux-core/bijux-dag/operations/compliance-gated-bulletin-workflow/) |
Schedule and backfill flows remain internal workflow lanes in v0.4.x. Their
presence in repository evidence is not a public runtime commitment.
## Internal Documentation
- [`ADAPTERS_AND_BACKENDS.md`](https://github.com/bijux/bijux-core/blob/main/crates/bijux-dag-runtime/docs/ADAPTERS_AND_BACKENDS.md): adapter
handshake, backend capabilities, containers, batch execution, and refusals.
- [`ARCHITECTURE.md`](https://github.com/bijux/bijux-core/blob/main/crates/bijux-dag-runtime/docs/ARCHITECTURE.md): execution flow, source
boundaries, dependency direction, stable exports, and extension decisions.
- [`CACHE_REPLAY_AND_EVIDENCE.md`](https://github.com/bijux/bijux-core/blob/main/crates/bijux-dag-runtime/docs/CACHE_REPLAY_AND_EVIDENCE.md): cache
identity, hit validation, replay eligibility, persistence, and repair.
- [`CONTRACTS.md`](https://github.com/bijux/bijux-core/blob/main/crates/bijux-dag-runtime/docs/CONTRACTS.md): owned execution semantics, effects,
state, backend, cache, replay, and failure contracts.
- [`EXECUTION_AND_SCHEDULING.md`](https://github.com/bijux/bijux-core/blob/main/crates/bijux-dag-runtime/docs/EXECUTION_AND_SCHEDULING.md): admission,
readiness, attempts, retries, cancellation, state invariants, and recovery.
- [`FAILURE_AND_CANCELLATION.md`](https://github.com/bijux/bijux-core/blob/main/crates/bijux-dag-runtime/docs/FAILURE_AND_CANCELLATION.md): failure
classes, success acceptance, retry eligibility, cancellation propagation,
and retained recovery evidence.
## Related links
- [Crate contracts](https://github.com/bijux/bijux-core/blob/main/crates/bijux-dag-runtime/docs/CONTRACTS.md)
- [Crate changelog](https://github.com/bijux/bijux-core/blob/main/crates/bijux-dag-runtime/CHANGELOG.md)
- [DAG handbook](https://bijux.io/bijux-core/bijux-dag/)
- [Package docs](https://bijux.io/bijux-core/bijux-dag/packages/bijux-dag-runtime/)