The Dungeon Master Pattern

Channels: The Client-Server Communication Layer

Channels are how clients talk to documents. A channel is a typed endpoint that accepts a specific message type and runs handler code. Think of them as the API surface of a document:

message Say { string text; }

channel say(Say msg) {
  _chat <- {who: @who, text: msg.text, when: Time.datetime()};
}

But the real power shows up with incomplete channels -- channels declared without handlers. These exist so the state machine can ask specific clients for input, flipping the usual client-server relationship:

message Move { int x; int y; }
channel<Move> move_channel;

Fetch and Await: Durable Async That Survives Anything

The fetch and await pair is where the dungeon master pattern gets interesting. fetch requests input from a specific principal (player). await blocks until that input arrives. But this is not a busy-wait. The document state -- including the pending request -- is persisted to durable storage. The server can crash, restart on a different machine, and the await will resume exactly where it left off when the player finally responds.

#playerTurn {
  future<Move> f = move_channel.fetch(current_player);
  Move m = f.await();
  applyMove(m);

  if (checkWinner()) {
    transition #gameOver;
  } else {
    current_player = getNextPlayer();
    transition #playerTurn;
  }
}

Beyond fetch, channels provide decide and choose for structured input. decide(principal, options[]) restricts the player to picking from a set of valid options -- no cheating. choose(principal, options[], limit) lets the player select a subset. Both return futures and are fully durable:

channel<Play> play;

#playerTurn {
  list<Play> open = iterate _board where piece == @no_one;
  if (play.decide(current_player, @convert<Play>(open)).await() as pick) {
    applyMove(pick);
  }
  transition #nextTurn;
}

The separation of fetch and await into two calls is deliberate. It enables parallel requests to multiple players:

#getResponses {
  future<Answer> f1 = answer.fetch(player1);
  future<Answer> f2 = answer.fetch(player2);

  // Both players respond independently. Order doesn't matter.
  Answer a1 = f1.await();
  Answer a2 = f2.await();

  processAnswers(a1, a2);
  transition #nextPhase;
}

Even though we await player1 first, player2 can respond at any time. If player2 responds before player1, their answer is queued and immediately available when we reach f2.await().

Delayed Transitions: Durable Timers Without Cron

Add in followed by a number of seconds to delay a transition:

#bidding {
  transition #auctionClosed in 3600;  // Close after 1 hour
}

These delayed transitions are durable. Schedule a transition for one hour from now, crash the server after 30 minutes, and the transition still fires 30 minutes after recovery. No external cron jobs. No Redis-backed timers. No SQS delay queues.

This matters for real applications. Auction deadlines, session timeouts, scheduled events -- they all execute reliably as a built-in property of the document.

Why This Kills the Saga Pattern

The saga pattern exists because distributed systems need multi-step workflows that can fail partway through. Each step has a compensating transaction to undo it if a later step fails. In practice, this means:

1. You need an external saga orchestrator (or choreography bus)
2. Every step needs a forward action AND a compensating action
3. You need to handle the case where the compensating action itself fails
4. You need idempotency keys everywhere
5. You need a persistent store for saga state
6. You need monitoring for stuck sagas

Saga Pattern (Microservices)

#setupGame {
  invoke #shuffleDeck;
  invoke #dealCards;
  invoke #setupBoard;
  transition #playRound;
}

#round {
  future<DrawCount> draw_fut = how_many.fetch(current_player);
  DrawCount draw = draw_fut.await();

  invoke #drawCards;
  invoke #playCard;

  current_player = (current_player == player1) ? player2 : player1;

  if (deckEmpty()) {
    transition #scoring;
  } else {
    transition #round;
  }
}