Skip to content
legra-aiPublic

About

Distributed task-tree values: W3C trace-compatible task identities under an application-supplied URN scheme, validated lifecycle, lineage, and progress

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

tasktree

Crates.io Documentation CI License Downloads

Distributed task-tree values: W3C trace-compatible task identities under an application-supplied URN scheme, validated lifecycle transitions, parent-child lineage, progress, and timestamps.

This crate is deliberately runtime-independent — no async, no I/O, no executor. It is the value layer a distributed task engine is built on; the engine (registries, admission, execution, event streams) is yours.

  • Identity — a TaskTreeId is W3C trace-sized (16 bytes) and a TaskNodeId span-sized (8 bytes), so every task maps directly onto Trace Context: a tree id parses from its URN, a bare trace id, or a full traceparent header. Every tree has one reserved root node, and TaskId::child mints siblings inside the tree.
  • Your namespace, not ours — identities are minted under a UrnScheme the application defines; this crate ships no namespace of its own, so no third party can mint another system's URNs and two systems' identities can never be confused, even at the type level. Prefixes are validated at compile time.
  • Lifecycle — TaskStatus with a validated transition machine (admitted → queued → running → sealing → done/failed/cancelled); terminal states admit no exits, and the irreversible sealing region refuses cancellation. Illegal edges are unrepresentable as TaskTransition values.
  • Terminal cause — every move into failed or cancelled carries a TerminalCause: the originating event (caller cancel, session close, deadline, exhausted budget, executor failure, stall, lost node, host eviction, host restart), whether this task was its subject or collateral of the cascade, the terminal status that event ends in, and the party (FaultSide) it is attributed to. A cause-less terminal edge, a cause on a non-terminal edge, or a cause that ends in the other terminal status is refused at construction and at deserialization.
  • Lineage — TaskLineage proves a parent-child edge is within one tree and never self-referential, enforced again on deserialization.
  • Progress — typed units, bounded aggregation, display fractions, lifecycle timestamps, and pure per-task publication decisions. The publication gate distinguishes first observations, step changes, counter resets and completion from ordinary interval reporting; it reads no clock and performs no event delivery.
  • Ordered activity — OrderedActivity attributes an application payload to one task at a checked ActivitySeq stream position; the payload declares its ActivityDurability (Retained evidence is never dropped or merged, Coalescible diagnostics may be replaced by a newer record).
  • Bounded recovery — a RecoveryCheckpoint retains every nonterminal task plus at most a TerminalTailLimit of terminal ones, and names the cursor from which incremental records replay. Construction and streaming deserialization share one validator that refuses the first duplicate, mis-keyed, lifecycle-invalid (TaskStatus::validate_snapshot) or over-limit task before reading further. No storage, no I/O.
  • Resource envelopes — an abstract Tokens unit with checked arithmetic; a TokenBudget that attenuates to children running in the same process and reserves shares for delegated ones (siblings split the pool, nothing is handed out twice); ResourceBudget, ResourceReservation, and ResourceActual that compose bottom-up per resource (sequential children sum wall time, parallel children take the maximum; tokens and wall work always sum); and a typed BudgetRefusal. No prices, factors, or ledgers: what a token buys is the application's business.
use tasktree::{TaskId, TaskLineage, TaskStatus, UrnScheme};

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
struct MyUrn;

impl UrnScheme for MyUrn {
    const TASK_PREFIX: &'static str = "urn:my-app:task:";
    const TREE_PREFIX: &'static str = "urn:my-app:task-tree:";
}

let root: TaskId<MyUrn> = TaskId::generate();
let child = root.child();
assert!(root.as_str().starts_with("urn:my-app:task:"));

let edge = TaskLineage::try_new(child, root).expect("same tree, not self");
assert!(TaskStatus::Running.validate_transition(TaskStatus::Sealing).is_ok());
# let _ = edge;

Progress publication is a separate decision from storing observed counters:

use tasktree::{ProgressPublishDecision, ProgressPublishState};

let mut publications = ProgressPublishState::default();
let decision = publications.decide(Some("copy"), 1, Some(10), 0);
assert_eq!(decision, ProgressPublishDecision::First);
publications.record_published(Some("copy"), 1, Some(10), 0);
assert_eq!(
    publications.decide(Some("copy"), 2, Some(10), 500),
    ProgressPublishDecision::Suppressed,
);
assert_eq!(
    publications.decide(Some("copy"), 2, Some(10), 1_000),
    ProgressPublishDecision::PercentChanged,
);

The caller supplies timestamps and records its selection explicitly. Ordinary updates have a one-second floor; first observations, label changes, resets and first completion remain distinguishable. A runtime can apply additional shared publication limits after this decision. This bookkeeping is not a durable task record, an event sink, or a scheduler.

Serde uses the URN string form throughout, and every deserialization re-validates: a foreign prefix, a zero identity, or an illegal transition never becomes a value.

License

Licensed under either of:

Links

About

Distributed task-tree values: W3C trace-compatible task identities under an application-supplied URN scheme, validated lifecycle, lineage, and progress

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages