For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

Run Effect at the integration boundary

A service is a named interface. A Layer describes how to build a service and supply its dependencies. A runtime executes Effects. A managed runtime keeps constructed services until disposal.¶

Keep service methods as Effects. Run them where a process, framework, or callback requires execution. The integration boundary owns the runtime’s lifetime.¶

Use the calling framework’s Effect integration

A managed runtime is one integration tool. It is not required inside every Effect application.¶

The basics page¹⁷ shows CLI, Worker and test execution boundaries. The CLI’s composition root¹⁶ supplies requirements before running its program.¶

Do not replace an existing Effect bridge

The development backend already uses a router bridge:¶

const { handler } = HttpRouter.toWebHandler(
  devtoolsRoutes(contentCapabilities).pipe(Layer.provide(nodeContentLayer)),
  {
    disableLogger: true,
  }
);

export const backend: BackendFetch = handler;

export const devtoolsBackend: BackendFetch = handler;

toWebHandler also returns a disposal function. This module keeps only the handler; the excerpt does not prove explicit disposal on development-server shutdown. Do not present that missing shutdown check as established resource cleanup.¶

Own a foreign runtime explicitly

The checked adapter exposes a small Promise API to a hypothetical foreign framework. It creates one managed runtime from a counted resource Layer.¶

export const makeForeignRuntimeBoundary = (options: {
  readonly acquired: Ref.Ref<number>;
  readonly released: Ref.Ref<number>;
}) => {
  const runtime = ManagedRuntime.make(BoundaryResource.layer(options));

  const read = Effect.gen(function* readBoundaryResource() {
    const resource = yield* BoundaryResource;

    return yield* resource.read;
  });

  return {
    close: runtime.dispose.bind(runtime),
    // @effect-diagnostics-next-line asyncFunction:off -- This foreign framework boundary exposes a native Promise API.
    read: async () => await runtime.runPromise(read),
  };
};

Effect stays inside the adapter. Callers receive a Promise-facing read and an explicit close.¶

The Layer builds on first use. Later calls reuse the built service context. close disposes the runtime and releases its resources. An integration must connect that close operation to its own shutdown path.¶

Keep native async functions at the foreign boundary. Domain methods return Effects.¶

Prove disposal through the foreign interface

The fixture’s test harness uses it.effect. The adapter under test owns the manual runtime.¶

      const acquired = yield* Ref.make(0);
      const released = yield* Ref.make(0);
      yield* Effect.acquireUseRelease(
        Effect.sync(() => makeForeignRuntimeBoundary({ acquired, released })),
        (boundary) =>
          Effect.gen(function* useForeignBoundary() {
            expect(yield* Ref.get(acquired)).toBe(0);
            expect(yield* Effect.tryPromise(boundary.read)).toBe("ready");
            expect(yield* Effect.tryPromise(boundary.read)).toBe("ready");
            expect(yield* Ref.get(acquired)).toBe(1);
            yield* Effect.promise(boundary.close);
            yield* Effect.promise(boundary.close);
            expect(yield* Ref.get(released)).toBe(1);

            const reused = yield* Effect.tryPromise(boundary.read).pipe(
              Effect.result
            );

            expect(Result.isFailure(reused)).toBe(true);
          }),
        (boundary) => Effect.promise(boundary.close)

The test wraps the subject’s native Promises with Effect adapters. Its acquire/use/release cleanup also closes the subject if an assertion fails. Check the running server’s shutdown behavior separately.¶

Integrate one calling framework at a time

1. Identify the process or framework that requires execution.¶
2. Keep the job’s input, output and failures typed inside Effect.¶
3. Build the needed services at the integration boundary.¶
4. Translate native callbacks or Promises at that edge.¶
5. Connect disposal to the host’s shutdown path.¶
6. Test the foreign interface and its cleanup.¶

Common mistakes

• Create a runtime for each domain method. Construction and cleanup lose a clear owner.¶
• Return native Promises throughout the domain. Replacing Effects with native Promises loses composition of typed failures³⁶ and requirements.¶
• Forget to dispose a long-lived runtime.¶
• Assume a framework’s shutdown is proven because the adapter returns a close function.¶

Effect idiom and house rule

• Runners and framework bridges execute Effects; runtime owners manage their Layers and disposal.¶
• In rat-stack, capabilities remain the shared interface for application actions¹⁸. A new runner does not authorize a handler that skips the capability contract²¹.¶
• In rat-stack, test harnesses use Effect-aware tests²², not manually created runtimes.¶

Read scopes²⁰ when deciding what the integration owns. Read services¹⁶ before extracting the job from its host. Return to the Effect reading order¹⁷.¶

Last changed 2026-10-07 in f1a00f2. Source on GitHub. Change log.

Content updated 2026-10-06.