Server composition, activation, and readiness

Chapter 5 ended with one resolved ServerConfig. It does not get passed to a constructor that imperatively starts everything. runServer launches an Effect layer whose acquisition builds a graph of platform services, application services, routes, long-running roots, and release finalizers. A second mechanism—the activation barrier—controls when already-acquired roots may begin external work.

The server is a scoped graph

flowchart TB
  C[ServerConfig] --> P[Bun or Node platform]
  P --> DB[SQLite + migrations]
  P --> OS[filesystem · process · PTY · HTTP]
  DB --> D[persistence · auth · settings]
  D --> K[orchestration · providers · VCS · checkpoints]
  OS --> K
  K --> E[terminal · preview · workspace · cloud · telemetry]
  E --> R[HTTP API · assets · WebSocket RPC · MCP]
  R --> H[scoped HTTP server]
  A{{activation deferred}} -.opens after preparation.-> K
  A -.opens after preparation.-> E

The graph is broad because the environment server is the execution authority from Chapter 1. Composition still preserves boundaries: each service exposes a typed interface, layers declare requirements, and the launched scope owns acquisition and release. makeServerLayer is the composition root; Layer.launch keeps it alive.

SQLite is acquired before command traffic

The SQLite layer configures a busy timeout, enables foreign keys, selects WAL, and runs a statically ordered migration manifest during acquisition. At this revision the manifest contains 41 migrations. That number is a fact about the pinned source, not a compatibility promise for later revisions.

Four signals that sound similar but are not

The listener can therefore exist while every route effect waits behind global middleware; a separate FIFO startup queue also holds WebSocket-dispatched commands. That is intentional: routes need a real bound address before presentation and remote-access setup can be prepared, but external work must not race ahead of a candidate runtime that has not crossed its activation boundary.

      yield* Effect.logDebug("startup phase: waiting for http listener");
      yield* runStartupPhase("http.wait", Deferred.await(httpListening));
      yield* runStartupPhase(
        "auxiliary-roots.parked",
        options?.awaitAuxiliaryParked ?? Effect.void,
      );
 
      // This is the prepared boundary. Every dependency has been acquired and
      // every runtime root has confirmed that it is parked before this request.
      const updateOutcome = yield* launcher.prepareTrial;
      yield* runStartupPhase(
        "welcome.publish",
        lifecycleEvents.publish({
          version: 1,
          type: "welcome",
          payload: { environment, ...welcomeBase },
        }),
      );
      yield* options?.activate ?? Effect.void;
 
      yield* Effect.logDebug("Accepting commands");
      yield* commandGate.signalCommandReady;
      yield* runStartupPhase(
        "ready.publish",
        lifecycleEvents.publish({
          version: 1,
          type: "ready",
          payload: {
            at: DateTime.formatIso(yield* DateTime.now),
            environment,
            ...(updateOutcome === undefined ? {} : { updateOutcome }),
          },
        }),
      );
      yield* Effect.logDebug("startup phase: complete");

After activate, the parked fibers are released concurrently. Heartbeat, browser/headless presentation, optional auto-bootstrap welcome, runtime-state persistence, and remote-access work may interleave with command admission and the ready publication. The flow orders the gate operations; it does not serialize all post-activation side effects.

Why park before activating?

forkParked is small but architectural. Its child fiber first fulfills a “parked” deferred and then waits on ServerActivation. The parent can prove all participating roots exist and are waiting before it releases a single shared gate. That prevents one early root from acting against a partially prepared graph.

This is synchronization, not a global transaction. Once activation opens, roots can perform filesystem, provider, Tailscale, cloud, browser, or other side effects with their own failure handling. Effect scopes provide release ownership; they do not magically roll back every effect that crossed an external boundary.