Package Architecture

< Performance | Up: Introduction | Index | State, Reader & Writer >

Skuld is distributed across seven independently-versioned Hex packages. This page explains what each package provides, how they depend on each other, and which effects live where.

Packages

Package	What it provides
`skuld`	Core computation engine (`Comp`), syntax macros (`Syntax`), and foundational effects including `Command` and `Transaction`
`skuld_concurrency`	Cooperative coroutines, the `FiberPool` scheduler, `Channel`/`Brook` streaming, and `AsyncCoroutine` process bridging
`skuld_port`	`Port` effect for dispatching to pluggable backends, `EffectfulFacade` for typed contracts, and `Adapter` for bridging effectful and plain code
`skuld_process`	`Parallel` for multi-process fan-out and `AtomicState` for process-level mutable state
`skuld_durable`	`SerializableCoroutine` for pause-serialize-resume workflows and `EffectLogger` for execution logging and replay
`skuld_query`	`Query` do-notation for auto-batching data fetches via dependency analysis and concurrent `FiberPool` dispatch (Haxl-style)
`skuld_repo`	Effectful Ecto Repo integration with `InMemory` (closed-world store), `Ecto` adapter, and `Stub` (stateless test double)

Dependency Layers

skuld
 ├── skuld_concurrency
 │    ├── skuld_durable
 │    └── skuld_query
 ├── skuld_port
 │    └── skuld_repo
 └── skuld_process

skuld is the sole base dependency. Every other package depends on it and shares its module namespace (Skuld.*). Beyond that, packages only depend on what they need:

skuld_concurrency adds coroutines and the scheduler — everything that needs concurrent fibers builds on this.
skuld_durable depends on skuld_concurrency for the coroutine infrastructure that SerializableCoroutine wraps.
skuld_query depends on skuld_concurrency for FiberPool-driven concurrent batch dispatch.
skuld_port adds the boundary abstraction. skuld_repo depends on it for the Port-based Repo facade.

Effect Map

Effect	Package
`State`	`skuld`
`Reader`	`skuld`
`Writer`	`skuld`
`Throw`	`skuld`
`Bracket`	`skuld`
`Fresh`	`skuld`
`Random`	`skuld`
`FxList` / `FxFasterList`	`skuld`
`Yield`	`skuld`
`Command`	`skuld`
`Transaction`	`skuld`
`Coroutine`	`skuld_concurrency`
`FiberPool`	`skuld_concurrency`
`Channel`	`skuld_concurrency`
`Brook`	`skuld_concurrency`
`AsyncCoroutine`	`skuld_concurrency`
`Task`	`skuld_concurrency`
`Port`	`skuld_port`
`Port.EffectfulFacade`	`skuld_port`
`Adapter`	`skuld_port`
`Parallel`	`skuld_process`
`AtomicState`	`skuld_process`
`SerializableCoroutine`	`skuld_durable`
`EffectLogger`	`skuld_durable`
`Query` / `QueryBlock`	`skuld_query`
`Repo`	`skuld_repo`
`Transaction.Ecto`	`skuld_repo`

Mental Model

The Skuld ecosystem is organised around the core Comp engine. Foundational effects ship with the base skuld package; everything else is opt-in:

                          Comp
                     (lazy computation,
                      evidence-passing,
                      scoped handlers)
                            │
      ┌─────────────────────┼───────────────────────────┐
      │                     │                           │
 //skuld              //skuld_concurrency           //skuld_port
 //(core)                  │                      //skuld_repo
      │                     │                           │
      │                 Coroutine                ┌──────┼────┐
      │                     │                    │      │    │
 State, Reader,    ┌────────┼─────────┐          │      │  Port
 Writer, Throw,    │        │         │          │      │  Port.EffectfulFacade
 Bracket, Fresh,   │  Serializable-   │          │      │  Repo
 Random, FxList,   │   Coroutine      │          │      │
 Yield             │   (skuld_durable)│          │      │
                   │                  │          │      │
              AsyncCoroutine     FiberPool     │  Adapter
                   │                 │          │  Adapter.EffectfulContract
                   │                 ├─────────┐│
              skuld_process         │         ││
                   │                 │         ││
              Parallel         Channel    Task   ││
              AtomicState         │              ││
                                Brook            ││
                                                 ││
                                            Query.Contract
                                            QueryBlock
                                            (skuld_query:
                                             auto-batches fetches
                                             via FiberPool)

Start with skuld. It gives you the computation engine and the foundational effects — everything you need to write pure effectful code with handler-swapping for deterministic testing.

Add sibling packages as you need their capabilities:

Want cooperative concurrency or streaming? Add skuld_concurrency.
Calling external services behind a contract? Add skuld_port.
Building durable, serialisable workflows? Add skuld_durable.
Eliminating N+1 queries across remote APIs? Add skuld_query.
Using Ecto and want InMemory test doubles? Add skuld_repo.
Fanning work out across processes? Add skuld_process.

Each package is opt-in. A simple computation that only uses State and Reader needs nothing beyond skuld.

< Performance | Up: Introduction | Index | State, Reader & Writer >

← Previous Page Performance

Next Page → State, Reader & Writer