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.0 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.0 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

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.

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

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: adapter handshake, backend capabilities, containers, batch execution, and refusals.
• ARCHITECTURE.md: execution flow, source boundaries, dependency direction, stable exports, and extension decisions.
• CACHE_REPLAY_AND_EVIDENCE.md: cache identity, hit validation, replay eligibility, persistence, and repair.
• CONTRACTS.md: owned execution semantics, effects, state, backend, cache, replay, and failure contracts.
• EXECUTION_AND_SCHEDULING.md: admission, readiness, attempts, retries, cancellation, state invariants, and recovery.
• FAILURE_AND_CANCELLATION.md: failure classes, success acceptance, retry eligibility, cancellation propagation, and retained recovery evidence.

Related links

• Crate contracts
• Crate changelog
• DAG handbook
• Package docs