# logicaffeine_runtime

> Deterministic, replayable concurrency runtime for the LOGOS interpreter and VM: task scheduler, channels, Select, timers, seed and trace

Every public module and item of `logicaffeine_runtime`, module by module, each with its one-line summary and its address. Item pages hold the full signature, documentation, trait implementations and a link to the source.

- Crate page: [logicaffeine_runtime](https://docs.logicaffeine.com/logicaffeine_runtime/)
- All items on one page: [logicaffeine_runtime/all](https://docs.logicaffeine.com/logicaffeine_runtime/all)
- Source: [src/logicaffeine_runtime/lib.rs](https://docs.logicaffeine.com/src/logicaffeine_runtime/lib.rs)
- Every crate: [llms.txt](https://docs.logicaffeine.com/llms.txt)

## logicaffeine_runtime

- [mod channel](https://docs.logicaffeine.com/logicaffeine_runtime/channel/): Channels — FIFO, bounded, move-semantics pipes (the language’s `Pipe`).
- [mod config](https://docs.logicaffeine.com/logicaffeine_runtime/config/): Scheduler configuration — annotatable knobs with a nice default.
- [mod executor](https://docs.logicaffeine.com/logicaffeine_runtime/executor/): The work-stealing M:N native driver.
- [mod payload](https://docs.logicaffeine.com/logicaffeine_runtime/payload/): `RtPayload` — the `Send`-able value subset that crosses task (and OS-thread) boundaries via channels.
- [mod scheduler](https://docs.logicaffeine.com/logicaffeine_runtime/scheduler/): The scheduler core + cooperative driver.
- [mod seed](https://docs.logicaffeine.com/logicaffeine_runtime/seed/): Seed, deterministic RNG, and the choice trace — the determinism contract.
- [mod task](https://docs.logicaffeine.com/logicaffeine_runtime/task/): Tasks — the unit the scheduler multiplexes.

## logicaffeine_runtime::channel
Channels — FIFO, bounded, move-semantics pipes (the language’s `Pipe`).

- [struct ChanId](https://docs.logicaffeine.com/logicaffeine_runtime/channel/struct.ChanId): A scheduler-assigned channel handle.

## logicaffeine_runtime::config
Scheduler configuration — annotatable knobs with a nice default.

- [struct SchedulerConfig](https://docs.logicaffeine.com/logicaffeine_runtime/config/struct.SchedulerConfig): All scheduler knobs, bundled. Has a `Default` and fluent setters so it is easy to annotate while still having a sensible baseline.
- [enum ClockMode](https://docs.logicaffeine.com/logicaffeine_runtime/config/enum.ClockMode): How the scheduler’s clock advances.
- [enum SchedulePolicy](https://docs.logicaffeine.com/logicaffeine_runtime/config/enum.SchedulePolicy): The ready-task selection discipline. Determinism holds under every policy: `Fifo`/`Lifo`/`RoundRobin`/`Priority` are deterministic by construction, and `Random` resolves its pick through the seeded `Chooser`, so it is reproducible under a fixed seed.

## logicaffeine_runtime::executor
The work-stealing M:N native driver.

- [struct SpawnDesc](https://docs.logicaffeine.com/logicaffeine_runtime/executor/struct.SpawnDesc): A `Send` task descriptor: which function to run, its already-materialised arguments, its scheduling priority, and whether it is the run’s main task. This is what a worker turns into a `!Send` task body locally.
- [struct WsOutcome](https://docs.logicaffeine.com/logicaffeine_runtime/executor/struct.WsOutcome): The result of a work-stealing run.
- [enum ResumeKind](https://docs.logicaffeine.com/logicaffeine_runtime/executor/enum.ResumeKind): How a worker should (re)enter a task body on its next poll. Every variant is `Send` (`FuncIdx` is `u16`, `RtPayload` is `Send`, ids are `Copy`).
- [fn run_workstealing_seeded](https://docs.logicaffeine.com/logicaffeine_runtime/executor/fn.run_workstealing_seeded): Run a concurrent program on the work-stealing M:N driver under `seed`.
- [type FuncIdx](https://docs.logicaffeine.com/logicaffeine_runtime/executor/type.FuncIdx): An opaque function index, from the runtime’s view — the compile crate’s `FuncIdx` (a `u16`), kept local so this crate stays dependency-free.

## logicaffeine_runtime::payload
`RtPayload` — the `Send`-able value subset that crosses task (and OS-thread) boundaries via channels.

- [enum RtPayload](https://docs.logicaffeine.com/logicaffeine_runtime/payload/enum.RtPayload): A self-contained, `Send` value that can move between tasks and threads.

## logicaffeine_runtime::scheduler
The scheduler core + cooperative driver.

- [struct ChanView](https://docs.logicaffeine.com/logicaffeine_runtime/scheduler/struct.ChanView): A read-only view of one channel for `Scheduler::snapshot`.
- [struct SchedSnapshot](https://docs.logicaffeine.com/logicaffeine_runtime/scheduler/struct.SchedSnapshot): A deterministic, read-only snapshot of the scheduler between steps — the observability seam the browser drive loop emits to the Studio so a running concurrent program shows its live task and channel state instead of freezing the UI.
- [struct Scheduler](https://docs.logicaffeine.com/logicaffeine_runtime/scheduler/struct.Scheduler): The deterministic task scheduler.
- [struct TaskView](https://docs.logicaffeine.com/logicaffeine_runtime/scheduler/struct.TaskView): A read-only view of one task for `Scheduler::snapshot`.
- [enum RunOutcome](https://docs.logicaffeine.com/logicaffeine_runtime/scheduler/enum.RunOutcome): The result of running a scheduler to quiescence.
- [enum TaskStateKind](https://docs.logicaffeine.com/logicaffeine_runtime/scheduler/enum.TaskStateKind): A public, read-only projection of a task’s scheduling state — what the Studio’s Tasks/Channels strip renders. Mirrors the private `TaskState` without exposing the task body or any mutable handle.
- [fn narrate_deadlock](https://docs.logicaffeine.com/logicaffeine_runtime/scheduler/fn.narrate_deadlock): Narrate a deadlock as English prose: the cooperative deterministic runtime has PERFECT information, so the explanation is a proof, not a heuristic — who waits, on what, and how full each channel is. Fed the snapshot taken when the scheduler proved the deadlock.
- [fn run_with_seed](https://docs.logicaffeine.com/logicaffeine_runtime/scheduler/fn.run_with_seed): Run `setup` (which spawns tasks and creates channels) under a fresh recording scheduler seeded by `seed`, returning the outcome and the scheduling trace.
- [fn run_with_trace](https://docs.logicaffeine.com/logicaffeine_runtime/scheduler/fn.run_with_trace): Re-run `setup` under a replaying scheduler driven by `trace`, returning the outcome.

## logicaffeine_runtime::seed
Seed, deterministic RNG, and the choice trace — the determinism contract.

- [struct ChoicePoint](https://docs.logicaffeine.com/logicaffeine_runtime/seed/struct.ChoicePoint): One recorded nondeterministic decision: its kind, how many options were available, and which index was taken. This shape is intentionally id-agnostic, so the trace format does not depend on `TaskId`/`ChanId`/etc.
- [struct SchedSeed](https://docs.logicaffeine.com/logicaffeine_runtime/seed/struct.SchedSeed): The scheduling seed. A fixed seed makes execution fully deterministic.
- [struct SchedTrace](https://docs.logicaffeine.com/logicaffeine_runtime/seed/struct.SchedTrace): A full record of the scheduling decisions a run made. Replay it for an exact re-execution, or compare two traces to detect a divergence.
- [struct SeededRng](https://docs.logicaffeine.com/logicaffeine_runtime/seed/struct.SeededRng): A small, deterministic, WASM-safe PRNG (SplitMix64).
- [enum ChoiceKind](https://docs.logicaffeine.com/logicaffeine_runtime/seed/enum.ChoiceKind): The class of a scheduling decision — recorded so replay can detect divergence.
- [enum Chooser](https://docs.logicaffeine.com/logicaffeine_runtime/seed/enum.Chooser): The decision choke point: records (seeded) or replays scheduling choices.

## logicaffeine_runtime::task
Tasks — the unit the scheduler multiplexes.

- [struct TaskCtx](https://docs.logicaffeine.com/logicaffeine_runtime/task/struct.TaskCtx): Per-`poll` context: what the task was resumed with.
- [struct TaskId](https://docs.logicaffeine.com/logicaffeine_runtime/task/struct.TaskId): A scheduler-assigned task handle.
- [enum SelectArm](https://docs.logicaffeine.com/logicaffeine_runtime/task/enum.SelectArm): One arm of a `Select` (`Await the first of:`).
- [enum TaskStep](https://docs.logicaffeine.com/logicaffeine_runtime/task/enum.TaskStep): What a task asks the scheduler to do after a `poll`.
- [trait Task](https://docs.logicaffeine.com/logicaffeine_runtime/task/trait.Task): A schedulable unit of work. `'t` ties any spawned children to the lifetime of borrowed data the task closes over (e.g. the interpreter’s borrowed AST).