Build distributed programs as ordinary, composable values.

Actor toolkits make distributed work easy to start, but the resulting programs are operational artifacts: they run, but they cannot be passed around, inspected, or composed like ordinary values. Parapet keeps the actor model and adds the missing piece — handlers return data describing what should happen, not callbacks performing it.

That single decision unlocks the rest: you can lift a handler into a test harness, interpret it under any effect type, intercept and trace every event, run the same program on different runtimes, or evolve from a single JVM to a network without rewriting your domain code.

The bet is simple: an agent that can only invoke a small set of named operators generates fewer wrong programs than one let loose on raw threads, futures, and ad-hoc message buses. Parapet is that small set.

On the roadmap: a parapet-agent-pack — system prompt, .cursorrules / AGENTS.md, and a curated set of reference processes (counter, gossip ring, sharded KV) — so any AI assistant working in a Parapet repo writes correct code from the first prompt.

Start with First process → and DSL cheatsheet →. Then jump to Errors are events → to see how recovery composes.

If you've reached for akka-typed for typed actors or for cats-effect alone for concurrency, Parapet sits between them: actor semantics with cats-effect's F[_] polymorphism and a DSL you can interpret differently for tests, tracing, or replay.

Start with Composable DSL →, then The free encoding →, and finally Add a custom FlowOp → to see how the substrate extends without forking the core.

The big distributed substrates share a shape: processes / operators, supervision, transports, and a fixed bundle of guarantees baked in. Parapet keeps the shape but unbundles the guarantees — broadcast, replication, failure detection, and consensus are interchangeable connectors, not load-bearing parts of the runtime.

Start with Transport traits → and Module map →, then read the Roadmap → to see where reliable channels, sharding, and dataflow fit.

Add parapet-core to model processes. Add a runtime integration — parapet-cats-effect for production, parapet-pario for the reference runtime — when you want to run an application.

libraryDependencies ++= Seq(
  "io.parapet" %% "parapet-core"        % version,
  "io.parapet" %% "parapet-cats-effect" % version
)

For snapshots, enable Sonatype Central snapshots:

resolvers += "central-snapshots" at
  "https://central.sonatype.com/repository/maven-snapshots/"

F[_] is a type constructor: it takes a type and produces another one. F[Int] means "a description of a computation that, when interpreted, produces an Int". The shape of that description is left abstract on purpose — different effect runtimes encode it differently:

• cats.effect.IO[A] — Cats Effect's asynchronous, cancellable runtime.
• io.parapet.effect.ParIO[A] — Parapet's reference runtime.
• Your own monad, as long as you can provide the required type-class instances.

Parapet code is written against F[_] + a small set of capability traits. That keeps domain logic decoupled from any one runtime, and turns the choice of effect system into an end-of-the-world decision instead of one that bleeds into every module.

An effect is anything that interacts with the outside world or changes observable state: printing, reading a file, sleeping, sending a network packet, mutating a counter. A pure function only computes a value from its inputs.

An effect system is the part of a runtime that lets you build, combine, and execute descriptions of effects without performing them eagerly. In Parapet this is the Effect[F] type-class plus its companions:

trait Effect[F[_]]:
  def pure[A](value: A): F[A]
  def delay[A](thunk: => A): F[A]
  def suspend[A](thunk: => F[A]): F[A]
  def blocking[A](thunk: => A): F[A]
  def raiseError[A](error: Throwable): F[A]
  extension [A](fa: F[A])
    def flatMap[B](f: A => F[B]): F[B]
    def map[B](f: A => B): F[B]
    def handleErrorWith(f: Throwable => F[A]): F[A]

A process never calls Effect directly. It produces a DslF[F, Unit] program — the runtime's interpreter is the one that lifts each FlowOp into an F-effect.

Inside a handler, you build a small program using DSL operators such as send, fork, delay, and race. These operators do not perform anything on their own — they return values describing what should happen, which the runtime later executes.

// A program: "send Ping to peer, wait 100ms, send Pong to peer"
val program: DslF[F, Unit] =
  Ping ~> peer ++ delay(100.millis) ++ Pong ~> peer

Because the program is a value, you can store it, log it, test it under a fake interpreter, return it from a function that takes parameters, or compose it with another program with ++. This is the headline benefit of an effect system: behavior becomes data.

Under the hood, a DslF[F, A] is a Free[FlowOp[F, *], A] — an immutable tree of FlowOp nodes leading to a final result. The DslInterpreter walks that tree and turns each node into an F- effect that the chosen runtime can execute.

You do not need to know category theory to use Parapet. The encoding matters because it guarantees three properties:

• No accidental side effects at construction — building a program does not run it.
• Substitution works — equal programs produce equal effects.
• Inspection is possible — interpreters can rewrite, trace, or reorder.

The DSL is open: you can mix the parapet algebra with your own and route the extra cases through a tailor-made interpreter. The pattern is three steps — declare the new op, expose a smart constructor, then teach the interpreter how to run it.

// 1. Declare the op as a data type — pure, no behavior yet.
import io.parapet.free.{Free, Inject}

sealed trait MetricOp[F[_], A]
final case class Counter[F[_]](name: String, delta: Long)
    extends MetricOp[F, Unit]
final case class Timer[F[_], A](name: String, body: Free[MetricOp[F, _], A])
    extends MetricOp[F, A]

// 2. A smart constructor that lifts the op into your program type.
final class MetricOps[F[_], C[_]](using inject: Inject[[x] =>> MetricOp[F, x], C]):
  def increment(name: String, delta: Long = 1L): Free[C, Unit] =
    Free.inject[[x] =>> MetricOp[F, x], C, Unit](Counter[F](name, delta))

  def time[A](name: String)(body: Free[MetricOp[F, _], A]): Free[C, A] =
    Free.inject[[x] =>> MetricOp[F, x], C, A](Timer[F, A](name, body))

Programs that mix your algebra with the built-in one now type-check naturally. They are still pure values; the runtime decides what each node means.

A custom interpreter is a FunctionK from your algebra to F. Provide one that handles the new nodes; everything else delegates to the default Parapet interpreter. Override ParApp.interpreter (or your runtime equivalent) to plug it in.

import io.parapet.core.DslInterpreter.Interpreter
import io.parapet.free.{FunctionK, ~>}

final class MetricInterpreter[F[_]](underlying: Interpreter[F])(using metrics: Metrics[F])
    extends Interpreter[F]:

  def interpret(sender: ProcessRef.Unknown, target: ProcessRef.Unknown, trace: ExecutionTrace) =
    new FunctionK[[x] =>> MetricOp[F, x], F]:
      def apply[A](op: MetricOp[F, A]): F[A] = op match
        case Counter(name, delta)  => metrics.add(name, delta)
        case Timer(name, body)     => metrics.time(name)(
          body.foldMap(interpret(sender, target, trace))
        )
  // ... delegate the two other interpret(...) overloads to `underlying`.

Custom interpreters are the right place for cross-cutting concerns that do not belong in domain handlers: structured logging, distributed tracing, metrics, audit, replay.

Every process moves through the same four-stage lifecycle, driven by ordinary events the handler can observe and react to.

1. Registration. The application returns a process from processes(args), or another process calls register(parent, child). The runtime allocates a mailbox and wires the supervision graph.
2. Start. The runtime delivers Events.Start as the first event. Use it to send "ready" notifications, register children, open resources.
3. Running. Events are delivered in mailbox order; handle is invoked sequentially. Failures inside the handler are converted into a Failure event for the sender.
4. Stop. On graceful shutdown the runtime first stops every child, then delivers Events.Stop to the parent. Kill tears the process down without running handle.

class Server[F[_]] extends Process[F, Event, Nothing]:
  import dsl.*

  override def handle: Receive =
    case Start =>
      eval(println("opening port 8080"))
    case Stop =>
      eval(println("draining and closing"))

System events live in io.parapet.core.Events. They appear in handlers just like domain events, so there are no special hooks to learn.

A process can replace its active receive function with switch(newReceive). The swap is synchronous within the current program, so it composes naturally with state-machine flows.

class Door[F[_]] extends Process[F, Event, Nothing]:
  import dsl.*

  private def closed: Receive =
    case Open  => eval(println("opening")) ++ switch(opened)
    case Knock => eval(println("knock knock"))

  private def opened: Receive =
    case Close => eval(println("closing")) ++ switch(closed)
    case Enter => eval(println("welcome"))

  override def handle: Receive = closed

Processes themselves compose: a ++ b (alias a.and(b)) creates a process that runs both handlers when both can handle the event; a.or(b) tries a first and falls back to b. The resulting process inherits the left-hand ref and name.

class Core[F[_]] extends Process[F, Ping.type, Pong.type]:
  override def handle: Receive =
    case Ping => reply(Pong)

val core    = new Core[F]
val metrics = Process[F](_ => { case Ping => eval(counter.incrementAndGet()) })

val instrumented = core ++ metrics  // same ref as `core`

Channel turns the asynchronous mailbox model into a strict one-call-at-a-time dialog. It is useful when a handler needs a direct response before continuing, without inventing correlation ids by hand.

val client: ProcessRef[Event] = ProcessRef("client")
val ch     = new Channel[F](client)

val flow =
  register(client, ch) ++
    ch.send(Request("ping"), server.ref).flatMap {
      case scala.util.Success(Response(data)) => eval(println(s"got $data"))
      case scala.util.Failure(err)            => eval(println(s"failed: $err"))
    }

A channel rejects new requests while a request is in flight, which keeps the send-then-await pattern safe without locks.

When a handler raises, the runtime routes a Failure(envelope, error) event back to the original sender. Senders that handle Failure can retry, escalate, or convert the error into a domain event; senders that do not see one route the failure to the dead-letter sink.

class Client[F[_]](server: ProcessRef[Request]) extends Process[F, Event, Nothing]:
  import dsl.*

  override def handle: Receive =
    case Start =>
      Request("hello") ~> server
    case Failure(env, err) =>
      eval(println(s"server $server failed: ${err.getMessage}; retrying")) ++
        env.event ~> env.receiver

A DeadLetter wraps an envelope the runtime could not deliver — the receiver does not exist, has been terminated, or returned a Failure the sender did not handle. Dead letters are routed to a single well-known process whose ref is ProcessRef.DeadLetterRef.

The default implementation logs every dead letter with structured fields. Override ParApp.deadLetter to plug in your own — typical replacements push to a message bus, surface metrics, or persist the envelope for replay.

import io.parapet.core.processes.DeadLetterProcess

class AlertingDeadLetters[F[_]] extends DeadLetterProcess[F]:
  import dsl.*

  override val handle: Receive = {
    case DeadLetter(env, err) =>
      eval(metrics.deadLetters.increment()) ++
        alerts.publish(env, err)
  }

object MyApp extends CatsEffectParApp:
  override def deadLetter: IO[DeadLetterProcess[IO]] =
    IO.pure(new AlertingDeadLetters[IO])

  def processes(args: Array[String]): IO[Seq[Process[IO, ?, ?]]] = ...

parapet-net separates low-level byte transport from process-level events. Today it ships TCP request/reply over ZMQ and UDP-style datagrams over Aeron; the same process adapters can also wrap your own transport.

The adapter processes in io.parapet.net.processes lift those traits into the process world: ClientProcess, ServerProcess, and DatagramProcess. Application code sends typed events; transport details stay at the edge.

ZMQ is the current TCP backend. Create the low-level transport at the edge, then register ordinary Parapet processes around it.

import cats.effect.IO
import io.parapet.cats.CatsEffectParApp
import io.parapet.ProcessRef
import io.parapet.net.{Endpoint, TransportProtocol}
import io.parapet.net.processes.{ClientProcess, ServerProcess}
import io.parapet.net.transport.zmq.*

object ServerApp extends CatsEffectParApp:
  def processes(args: Array[String]) =
    val echoRef = ProcessRef[ServerProcess.Received | ServerProcess.Failed]("echo")
    val config = ZmqTcpServerConfig(
      bind = Endpoint(TransportProtocol.Tcp, "*", 5555)
    )

    ZmqTcpServer.make[IO](config).allocated.map { case (transport, _) =>
      val server = new ServerProcess[IO](transport, sink = echoRef)
      val echo = new Echo[IO](server.ref):
        override val ref = echoRef
      Seq(echo, server)
    }

object ClientApp extends CatsEffectParApp:
  def processes(args: Array[String]) =
    val config = ZmqTcpClientConfig(
      remote = Endpoint(TransportProtocol.Tcp, "server", 5555)
    )

    ZmqTcpClient.make[IO](config).allocated.map { case (transport, _) =>
      val client = new ClientProcess[IO](transport)
      val caller = new Caller[IO](client.ref)
      Seq(client, caller)
    }

In production code, keep the returned Resource alive for the application lifetime so sockets are closed cleanly on shutdown.

Because handlers are values, you can step a program through a test interpreter and assert on the emitted events instead of standing up a real network. The shared conformance specs in parapet-testkit are the same suite each backend has to satisfy — they are also a useful checklist when writing your own scenarios.

Parapet evolves in layers. Each layer is independently useful; later layers compose what earlier ones expose. The guiding principle: small composable behaviours, not a monolithic framework.

The full plan, including the next milestone (CRDT toolkit + anti-entropy gossiper, then sharding + cluster singleton) and anti-goals, lives in roadmap/ROADMAP.md.

Parapet is actively evolving. The core primitives are in place; higher-level modules such as reliable channels, failure detectors, broadcast, gossip, CRDTs, sharding, and observability grow independently.