Stateful wrapper and done-checker

Status: open/planned · Kind: adapter · Audience: system

Summary

• An optional stateful wrapper: register a status(id) function so the engine derives state, instead of threading a state map through every get_ready call.
• Convenience over the pure core; the base stays a function of (graph, state).
• Sub-capability of C-D2GO-readiness-scheduling.

Statement

The pure engine takes state as an argument on every call. When a caller’s state lives in its own store (task files, a database), threading a map is boilerplate. The stateful wrapper closes over the graph and a status source (or holds a mutable status map) and exposes ready / start / complete that derive state on demand. It is sugar: identical results to calling the pure get_ready with the same state.

The Rust design already absorbs half of this capability elsewhere. StatusSource (C-PPXU-status-model-and-trigger-rules) makes a closure over the caller’s store a first-class state argument, so the “register a done-checker” half needs no wrapper. What remains is the mutable-transitions half — start and complete — which is why this layer’s impact is low and its scope is smaller than the TypeScript sketch implied.

What it provides

• Tracker::new(graph) — an internal mutable status map.
• Tracker::with_status(graph, source) — reads from the caller’s store instead.
• Convenience transitions: start(id), complete(id, outcome), plus ready and explain.

use graph_scheduler::tracker::Tracker;

let mut t = Tracker::with_status(g, |id| store.status(id)); // engine derives state
t.ready(&ReadyOptions { limit: Some(4), ..Default::default() });

Inputs

• The graph; any StatusSource, or an internal mutable map.

Outputs

• The same frontier as the pure engine, plus convenience mutation methods.

Underlying implementation

• No code realizes this yet — the capability is planned. It would land with the crate at packages/rust/graph-scheduler/, the tracker in src/tracker.rs behind a default-off tracker Cargo feature. Until the crate exists there is no anchor to record here.
• Deferred past cutover, not part of v0.1. The engine holds its state on the lease and the run journal and re-reads it each tick, so it calls the pure frontier directly and has no use for a wrapper that owns state. This layer waits for a consumer that wants the convenience — the P-0012-rust-core-adapters-as-needed test, applied to a layer rather than a language.

Notes

• Opt-in, as a Cargo feature rather than a subpath export. The pure get_ready (C-PC3N-push-readiness-frontier) remains the canonical, testable core; the wrapper never adds behavior, only removes plumbing. Consumer-supplied-state vs. registered-checker was an explicit design choice — D-BPD8-graph-scheduler-api.
• Parity is the contract, not an aspiration: the tracker must return what get_ready returns for equivalent state, and a parity fixture proves it at every transition.

---

← Back to Capabilities