Crate shigoto 

shigoto (仕事) — the typed job-system primitive.

Umbrella crate. Re-exports the public surface of every sibling so consumers depend on shigoto = "0.1" and reach the full algebra via use shigoto::{Job, JobId, Scheduler, ...}; without naming every sub-crate.

Canonical spec: theory/SHIGOTO.md. Theory frame: theory/THEORY.md §IV (Motion).

Re-exports

pub use shigoto_gate;

Structs

AllUpstreamsTerminal

AllUpstreamsTerminal — every direct DAG predecessor has reached a terminal phase ({Succeeded, Skipped, Deadlettered}). The scheduler implicitly applies this gate to enforce DAG edge semantics; consumers don’t normally register it explicitly.

BudgetSpec

BudgetTree

Three-dimension budget envelope. Allocation checks every applicable limit (min-intersection): a job runs iff all three have slack.

Dag

Typed DAG of JobIds. Edges declare “to may not start until from reaches a terminal phase” (Succeeded | Skipped | Deadlettered). Acyclic by construction at edge-add time would require an O(V+E) check on every insert; instead, cycles are detected at toposort() / waves(), where consumers must run before scheduling anyway.

FailureRecord

Serialize/Deserialize so a FailureRecord round-trips through a durable store (e.g. shigoto_scheduler::SchedulerStore) across a restart — every field is already serde-safe (FailureKind derives it too), so this is a pure additive derive, not a shape change.

FixedClock

A settable clock for deterministic tests. Clock::now takes &self (the scheduler holds clocks behind Arc<dyn Clock>), so the stored instant lives behind a Mutex and moves only when the test calls FixedClock::set or FixedClock::advance — never on its own. This is what lets a test prove “job waits out its backoff, then retries” by moving the clock forward programmatically instead of sleeping for real.

FsmDefect

A single convergence-proof failure, with a message naming the offending state.

GateContext

Everything a Gate needs to make its decision: the job in question, the FSM snapshot (every other job’s phase), the DAG (so gates like AllUpstreamsTerminal can ask about predecessors).

IllegalTransition

Rejected transition — (from, signal) is not a legal FSM cell. Returning Result instead of panicking lets consumers report drift (an operator action attempting an illegal transition) without crashing the scheduler.

InMemorySink

In-memory JobId → Output map. The consumer reads via drain (clears + returns) or snapshot (clones + keeps) after ticks complete. Arc<Mutex<...>> interior so the same sink can be shared between the Job (recording) and the consumer (reading).

InProcessScheduler

Default scheduler — single-process, in-memory FSM state, sequential execution within a wave.

JobId

Typed identity for a Job. Stable across cycles + scheduler restarts.

JobKindId

Typed work-class identifier. Stored as String (not &'static str) so it serializes through serde without lifetime constraints. Cheap Clone is fine for the volume we expect (≤ ~100 kinds across the whole scheduler).

JsonFileSchedulerStore

A SchedulerStore backed by a single JSON file, written atomically (write to a .tmp sibling, then rename over the real path) so a crash mid-write never leaves a half-written, unparseable snapshot behind — the same technique formigueiro::FilePlanStore uses for its per-target state file.

NullSink

No-op sink — discards every output. Default for Jobs that don’t need their typed Output surfaced.

OperatorApproved

OperatorApproved — pass iff an external operator has flipped a pre-arranged flag. The flag itself lives in the consumer’s state store; this gate is a thin wrapper that holds an Arc<AtomicBool> or similar. v0.1 ships with a Closure variant that takes a Fn() -> bool for tests + ad-hoc cases.

SchedulerSnapshot

The subset of InProcessScheduler state that survives a restart. See the module doc for what’s deliberately excluded (Jobs, Gates, RetryPolicies — the executable graph, re-registered by the consumer).

Snapshot

Read-only snapshot of the scheduler’s current FSM map.

StoredJobState

One persisted job’s FSM progress.

SystemClock

Wall-clock time via chrono::Utc::now(). Default clock for InProcessScheduler::new.

TickReceipt

Derived per-tick rollup the scheduler emits on every tick.

TransitionEvent

UnhealedDrift

UrgencyWeights

Weights for the urgency score. Each term is multiplied and summed; tune to shift the balance between “most stale”, “furthest behind”, “most drifted”, and “longest starved”. Defaults bias toward closing real drift and honoring fairness, with staleness as a gentle background pressure.

Enums

BudgetError

DagError

DefectKind

#[non_exhaustive] is deliberate and load-bearing: it forces every downstream match to carry a wildcard, so the next defect kind this harness learns to detect is a non-breaking change instead of a fleet migration. It is free today — no crate outside shigoto references DefectKind at all (consumers call assert_convergent_fsm, which returns Result<(), String>).

GateAggregate

Aggregate gate outcome — what the cohort of gates collectively said. Per §III.9 individual gates return Pass / Vacuous / Wait / Skip; the aggregate is the worst outcome (Skip > Wait > Pass) per a typed reducer in shigoto-gate. We carry the rolled-up result here so the FSM stays language-agnostic about how the rollup is computed.

GateOutcome

One gate’s verdict.

JobPhase

FSM phase a Job inhabits. See theory/SHIGOTO.md §III.3 for the transition table.

JobScope

JobSubject

PriorityClass

Hard priority tier. Lower discriminant = scheduled first. A higher tier always precedes a lower one regardless of urgency — tiers express coarse operator intent; Schedulable::urgency is the fine sort within a tier.

RetryDecision

RetryOutcome

Retry decision from a RetryPolicy::decide() call. Same shape that shigoto-retry’s RetryDecision exposes — duplicated as a typed signal payload so the FSM stays in shigoto-types without a dependency on shigoto-retry.

RetryPolicy

SchedulerError

SchedulerStoreError

Signal

FSM driver — every legal way a Job’s phase can change. Exhaustive over the (JobPhase, Signal) cross-product per theory/SHIGOTO.md §IV.1; the advance table below enumerates every cell.

SkipReason

TransitionReason

Traits

Clock

A source of the current time for crate::InProcessScheduler. Production code uses SystemClock (the default); tests that need to assert backoff/retry timing without a real sleep use FixedClock.

ConvergentFsm

A typed finite-state lifecycle whose convergence can be proven mechanically.

ErasedJob

Trait-object dispatch surface. The scheduler holds Box<dyn ErasedJob> (Job itself isn’t object-safe because of the associated types); ErasedJob collapses the typed Output + Error to () + boxed error so the scheduler can store heterogeneous jobs in one DAG.

Gate

One typed precondition. Pure — no IO. Gate impls that “need” IO are antipatterns; the right shape is a Job that emits a typed fact and a downstream gate that checks the fact.

Job

The typed Job trait — what every consumer’s domain-specific job implements. Per theory/SHIGOTO.md §III.1.

JobError

JobInput

Inputs / Outputs / Errors implement these marker traits so the scheduler can serialize across boundaries when persistence lands.

JobOutput

OutputSink

Typed receiver for Job::Output values. Jobs call record on a successful execute so consumers (reconcile receipts, audit trails, dashboards) can read the typed outcomes the scheduler’s phase-tracking discards.

RecordingJob

Convenience trait that captures the most common Job authoring shape across pleme-io consumers: a Job whose typed Output flows through an OutputSink for consumer-side capture, and whose identity decomposes into (scope, kind, subject).

RetryDecider

Schedulable

A unit of pending work that can be ordered. Implement the eight accessors; the default urgency / rank_key give every consumer the same anti-starvation ordering for free.

Scheduler

SchedulerStore

A store for scheduler FSM state across restarts. A trait so the reference JsonFileSchedulerStore (workstation / single-process daemon) and a future durable impl (operator CRD / Postgres, per MAGMA-NATIVE’s “in-memory + DB-persisted, never the pod filesystem” destination) share one contract. Mirrors formigueiro::PlanStore’s shape one repo over.

TransitionEmitter

Receivers of TransitionEvent. Thin trait over the canonical shigoto_types::sink::Sink<TransitionEvent> so every consumer writing Arc<dyn TransitionEmitter> keeps working unchanged after the theory/CONVERGENCE-ADOPTION.md Phase 0.1 extraction. The blanket impl below means any Sink<TransitionEvent> impl auto-satisfies TransitionEmitter — no per-impl wiring at the consumer side.

Functions

advance

The canonical FSM driver. Pure: same (from, signal) always produces the same result. Exhaustive over JobPhase × Signal — adding a new phase or signal fails to compile until every cell of the cross-product is decided.

assert_convergent_fsm

The full forcing-function: closed-graph + terminal-soundness + no-traps + universal convergence. Ok(()) iff the FSM is convergent and well-formed; Err aggregates EVERY defect (so one run reports all problems, not the first).

pick

Like rank, but return only the top slots — the next wave to dispatch. Pair with [shigoto-budget] for the no-crash admission bound: rank picks the order, budget enforces the count.

rank

Order every eligible unit in pending, most-valuable-first. Ineligible units are dropped. Deterministic: equal-urgency units fall back to stable id, so the result is replayable.

Type Aliases

AuditFileEmitter

Append-only JSONL audit file. One event per line. Same shape as tend’s existing audit.rs so operators can grep both with the same tooling. Alias of the canonical shigoto_types::sink::AuditFileSink<TransitionEvent> — JSONL serialization is byte-identical (one serde_json::to_string per line + writeln! append).

MultiEmitter

Fan-out emitter — every inner sink receives every event. Alias of the canonical shigoto_types::sink::MultiSink<TransitionEvent>; inner sinks are Arc<dyn Sink<TransitionEvent>>.

NullEmitter

No-op emitter — the default for tests + consumers without observability wired up. Sinks should compose via MultiEmitter instead of stubbing this in production. Alias of the canonical shigoto_types::sink::NullSink<TransitionEvent>.