@akterjs/effect 0.0.0-stage → 0.1.0

package/src/runtime/akter.layer.ts

@@ -0,0 +1,208 @@
+import { Layer, String as Str } from "effect";
+import type { HttpServer, HttpServerError } from "effect/http";
+
+import { Akter as ContractAkter } from "#src/contract/akter.service";
+import type { ActorHost } from "#src/serve/engine/actor-host.service";
+import type { ActorsNotHostedError } from "#src/serve/engine/actors-not-hosted.errors";
+import type { ListenerNotLoopbackError } from "#src/serve/rpc/listener-not-loopback.errors";
+import { serveInspector } from "#src/serve/inspect/inspector.layer";
+import { serve } from "#src/serve/rpc/akter-server.layer";
+import type { ServedActor, ServeOptions } from "#src/serve/rpc/akter-server.layer";
+
+import { environments, historyRetention, jobs, local, localClient, migrate } from "./akter-local.layer.js";
+import { httpServer } from "./http-server.layer.js";
+
+const defaultPort = 4000;
+
+const loopback = "127.0.0.1";
+
+const bracketed = /^\[(?<address>.*)\]$/u;
+
+const defaultInspectorPort = 4001;
+
+interface InspectorOptions {
+  readonly allowedHosts?: readonly string[] | true;
+  readonly directory: string;
+  readonly port?: number;
+}
+
+export class Akter extends ContractAkter {
+  /** A data directory's environments and snapshots, read and changed without running an engine on it. */
+  public static readonly environments = environments;
+
+  public static readonly historyRetention = historyRetention;
+
+  /**
+   * The local engine's job runtime. Provide it under an app layer whose job handlers need the `WorkflowEngine`,
+   * beside `Akter.local`, so the handlers register on the engine that runs their jobs:
+   * `Akter.local(directory).pipe(Layer.provide(app.layer), Layer.provide(Akter.jobs))`.
+   */
+  public static readonly jobs = jobs;
+
+  public static readonly local = local;
+
+  public static readonly localClient = localClient;
+
+  public static inspector(options: InspectorOptions): Layer.Layer<HttpServer.HttpServer, HttpServerError.ServeError> {
+    const listener = { hostname: loopback, port: options.port ?? defaultInspectorPort };
+
+    return serveInspector({ allowedHosts: options.allowedHosts ?? [], directory: options.directory }).pipe(
+      Layer.provideMerge(httpServer(listener)),
+    );
+  }
+
+  public static readonly migrate = migrate;
+
+  public static serve<const Actors extends readonly ServedActor[]>(
+    options: ServeOptions<Actors>,
+  ): Layer.Layer<
+    HttpServer.HttpServer,
+    ActorsNotHostedError | HttpServerError.ServeError | ListenerNotLoopbackError,
+    ActorHost
+  > {
+    const hostname = Str.replace(bracketed, "$<address>")(options.hostname ?? loopback);
+    const listener = { hostname, port: options.port ?? defaultPort };
+
+    return serve(options).pipe(Layer.provideMerge(httpServer(listener)));
+  }
+}
+
+export { ActorJournal } from "#src/contract/history/actor-journal.service";
+
+export { LocalEnvironments } from "#src/serve/environment/local-environments.service";
+
+export type { Branching } from "#src/serve/environment/local-environments.service";
+
+export type { Snapshotting } from "#src/serve/environment/snapshot-operations.sql";
+
+export {
+  EnvironmentName,
+  LocalEnvironment,
+  LocalSnapshot,
+  Promotion,
+  SnapshotName,
+} from "#src/serve/environment/local-environment.schema";
+
+export { AlreadyExistsError } from "#src/serve/environment/environment-already-exists.errors";
+
+export { InUseError } from "#src/serve/environment/environment-in-use.errors";
+
+export { NotFoundError } from "#src/serve/environment/environment-not-found.errors";
+
+export type { LocalActorEngineServices } from "./local-actor-engine.layer.js";
+
+export { HostedAppBuildError } from "#src/serve/hosted/hosted-app-build.errors";
+
+export { MigrationHasher } from "#src/host/migration/migration-hasher.adapter";
+
+export { ActorAlreadyExistsError } from "#src/contract/actor/actor-already-exists.errors";
+
+export { ActorErasedError } from "#src/contract/actor/actor-erased.errors";
+
+export { ActorNotCreatedError } from "#src/contract/actor/actor-not-created.errors";
+
+export { ActorNotRegisteredError } from "#src/contract/actor/actor-not-registered.errors";
+
+export { ActorUnavailableError } from "#src/contract/client/actor-unavailable.errors";
+
+export { CallerNotAllowedError } from "#src/contract/caller/caller-not-allowed.errors";
+
+export { CommandIdExpiredError } from "#src/contract/command/command-id-expired.errors";
+
+export { CheckpointExpiredError } from "#src/contract/computer/checkpoint-expired.errors";
+
+export { ComputerHeldError } from "#src/contract/computer/computer-held.errors";
+
+export { ComputerLimitError } from "#src/contract/computer/computer-limit.errors";
+
+export { ComputerLostError } from "#src/contract/computer/computer-lost.errors";
+
+export { ComputerNotFoundError } from "#src/contract/computer/computer-not-found.errors";
+
+export { ComputersUnavailableError } from "#src/contract/computer/computers-unavailable.errors";
+
+export { StepNotFoundError } from "#src/contract/computer/step/step-not-found.errors";
+
+export { FileAccessDeniedError } from "#src/contract/file/access/file-access-denied.errors";
+
+export { FileNotFoundError } from "#src/contract/file/file-not-found.errors";
+
+export { FileTooLargeError } from "#src/contract/file/rpc/file-too-large.errors";
+
+export { BlobTransferError } from "#src/contract/file/blob-transfer.errors";
+
+export { FilesUnavailableError } from "#src/contract/file/files-unavailable.errors";
+
+export { HandlerFailedError } from "#src/contract/hosted/handler-failed.errors";
+
+export { InvalidFileRequestError } from "#src/contract/file/invalid-file-request.errors";
+
+export { InvalidRequestError } from "#src/contract/client/invalid-request.errors";
+
+export { BillingUnavailableError } from "#src/contract/spend/billing-unavailable.errors";
+
+export { SpendCapReachedError } from "#src/contract/spend/spend-cap-reached.errors";
+
+export { StorageLimitError } from "#src/contract/client/storage-limit.errors";
+
+export { ReservedMemberError } from "#src/contract/actor/reserved-member.errors";
+
+export { ReservedPayloadFieldError } from "#src/contract/job/reserved-payload-field.errors";
+
+export { StateUnreadableError } from "#src/contract/state/state-unreadable.errors";
+
+export { InvalidSecretNameError } from "#src/contract/secret/invalid-secret-name.errors";
+
+export { SecretUnavailableError } from "#src/contract/secret/secret-unavailable.errors";
+
+export { UnauthenticatedError } from "#src/contract/caller/unauthenticated.errors";
+
+export { CommandRejectedError } from "#src/host/command/command-rejected.errors";
+
+export { LayoutVersionError } from "#src/host/layout/layout-version.errors";
+
+export { MigrationEditedError } from "#src/host/migration/migration-edited.errors";
+
+export { MigrationFailedError } from "#src/host/migration/migration-failed.errors";
+
+export { MigrationMissingError } from "#src/host/migration/migration-missing.errors";
+
+export { ReservedNameError } from "#src/host/actor/reserved-name.errors";
+
+export { HistoryPrunedError } from "#src/host/command/history-pruned.errors";
+
+export { CommandIdReusedError } from "#src/host/command/command-id-reused.errors";
+
+export { ReplayCursorStalledError } from "#src/host/command/replay/replay-cursor-stalled.errors";
+
+export { ActorNotMigratedError } from "#src/serve/store/actor-not-migrated.errors";
+
+export { ActorsNotHostedError } from "#src/serve/engine/actors-not-hosted.errors";
+
+export { ListenerNotLoopbackError } from "#src/serve/rpc/listener-not-loopback.errors";
+
+export { StoreUnreadableError } from "#src/serve/store/store-unreadable.errors";
+
+export { ActorHost } from "#src/serve/engine/actor-host.service";
+
+export { Verify } from "#src/serve/verify/verify.layer";
+
+export type {
+  HistoryEntry,
+  HistoryOptions,
+  RecordedCommand,
+  UnreadableCommand,
+} from "#src/contract/history/actor-journal.service";
+
+export type { LocalMigration, MigratedActor } from "#src/serve/store/store-migrations.service";
+
+export type {
+  JournalPoint,
+  ReplayDifference,
+  ReplayedOutcome,
+  ReplayFailure,
+  ReplayReport,
+  ReplaySource,
+  ReplayWindow,
+  VerifyFailure,
+} from "#src/serve/verify/verify.layer";

package/src/runtime/blob-hashing.layer.ts

@@ -0,0 +1,21 @@
+import { createHash } from "node:crypto";
+
+import { Effect, Layer } from "effect";
+
+import { BlobHashing } from "#src/host/hash/blob-hashing.service";
+
+const sha256 = Effect.sync(() => {
+  const hash = createHash("sha256");
+
+  return {
+    digest: Effect.sync(() => hash.digest("hex")),
+    update: (bytes: Uint8Array): Effect.Effect<void> =>
+      Effect.sync(() => {
+        hash.update(bytes);
+      }),
+  };
+});
+
+const blobHashing: Layer.Layer<BlobHashing> = Layer.succeed(BlobHashing, { sha256 });
+
+export { blobHashing };

package/src/runtime/hosted-environment.layer.ts

@@ -0,0 +1,85 @@
+import { Context, Effect, Exit, Latch, Layer, Scope } from "effect";
+import type { FileSystem, Path } from "effect";
+
+import { LocalBlobHomes } from "#src/host/file/local-blob-home.service";
+import { SqliteDriver } from "#src/host/sqlite/sqlite-driver.service";
+import { UpkeepGate } from "#src/host/upkeep/execution-authority.pure";
+import { ActorHost } from "#src/serve/engine/actor-host.service";
+import { ActorLocation } from "#src/serve/engine/actor-location.service";
+import type { Cut } from "#src/serve/environment/snapshot-operations.sql";
+import { cutStore } from "#src/serve/environment/store-snapshot.sql";
+import { actorEngine } from "#src/serve/engine/actor-engine.layer";
+import { fileHomes } from "./local-actor-engine.layer.js";
+
+const quietFlag = 1;
+
+/**
+ * What an environment's engine needs from the local engine around it. The context also carries what isn't typed
+ * here: the app's handlers, the job engine their jobs run on, and settings such as the history retention.
+ */
+type EngineContext = Context.Context<FileSystem.FileSystem | Path.Path | SqliteDriver>;
+
+/** The environment the local engine serves now, on an engine of its own that closes with `scope`. */
+interface HostedEnvironment {
+  /** Open while the environment isn't quiet; its actors' upkeep waits at it. */
+  readonly gate: Latch.Latch;
+  readonly host: ActorHost["Service"];
+  readonly homes: LocalBlobHomes["Service"];
+  readonly location: ActorLocation["Service"];
+  readonly name: string;
+  readonly scope: Scope.Closeable;
+  /** The environment's store, the directory its shards and files are in. */
+  readonly store: string;
+}
+
+interface EnvironmentOpening {
+  readonly context: EngineContext;
+  readonly name: string;
+  readonly quiet: number;
+  readonly store: string;
+}
+
+/** The engine of one environment's store: its host, where its actors are, and its file home. */
+const environmentEngine = (
+  directory: string,
+): Layer.Layer<ActorHost | ActorLocation | LocalBlobHomes, never, FileSystem.FileSystem | Path.Path> =>
+  Layer.merge(actorEngine(directory), ActorLocation.directory(directory)).pipe(
+    Layer.provideMerge(fileHomes(directory)),
+  );
+
+/** Opens one environment's engine, quiet when its record says so, with every service it needs from `context`. */
+const openEnvironment = Effect.fnUntraced(function* openEnvironment({
+  context,
+  name,
+  quiet,
+  store,
+}: EnvironmentOpening): Effect.fn.Return<HostedEnvironment> {
+  const scope = yield* Scope.make();
+  const gate = yield* Latch.make(quiet !== quietFlag);
+  const engine = environmentEngine(store).pipe(Layer.provide(Layer.succeed(UpkeepGate, gate)));
+  const built = Layer.buildWithScope(engine, scope).pipe(Effect.provideContext(context));
+  const services = yield* Effect.onError(built, (cause) => Scope.close(scope, Exit.failCause(cause)));
+
+  return {
+    gate,
+    homes: Context.get(services, LocalBlobHomes),
+    host: Context.get(services, ActorHost),
+    location: Context.get(services, ActorLocation),
+    name,
+    scope,
+    store,
+  };
+});
+
+/** How a snapshot cuts the hosted environment's store: each actor under its command lock, under its files' hold. */
+const cutOf =
+  (context: EngineContext) =>
+  ({ homes, host, location, store }: HostedEnvironment): Cut =>
+  (into) =>
+    Effect.flatMap(homes.get, (home) =>
+      cutStore({ driver: Context.get(context, SqliteDriver), home, host, into, location, store }),
+    ).pipe(Effect.provideContext(context));
+
+export { cutOf, openEnvironment };
+
+export type { EngineContext, EnvironmentOpening, HostedEnvironment };

package/src/runtime/http-server.layer.ts

@@ -0,0 +1,29 @@
+import { createServer } from "node:http";
+
+import { layer as nodeHttpServer } from "@effect/platform-node/NodeHttpServer";
+import { Effect, Layer } from "effect";
+import type { FileSystem, Path } from "effect";
+import type { HttpServer, HttpServerError } from "effect/http";
+
+type PlatformHttpServer = Layer.Layer<
+  FileSystem.FileSystem | HttpServer.HttpServer | Path.Path,
+  HttpServerError.ServeError
+>;
+
+interface Listener {
+  readonly hostname: string;
+  readonly port: number;
+}
+
+export const httpServer = ({ hostname, port }: Listener): PlatformHttpServer => {
+  if ("Bun" in globalThis) {
+    return Layer.unwrap(
+      Effect.map(
+        Effect.promise(() => import("@effect/platform-bun/BunHttpServer")),
+        (BunHttpServer) => BunHttpServer.layer({ hostname, port }),
+      ),
+    );
+  }
+
+  return nodeHttpServer(createServer, { host: hostname, port });
+};

package/src/runtime/local-actor-engine.layer.ts

@@ -0,0 +1,33 @@
+import { Effect, Layer, Path } from "effect";
+import type { FileSystem } from "effect";
+import { SecureRandom } from "effect/crypto";
+
+import type { ActorRegistry } from "#src/contract/actor/actor-registry.service";
+import type { ActorJournal } from "#src/contract/history/actor-journal.service";
+import { LocalBlobHomes } from "#src/host/file/local-blob-home.service";
+import { SqliteDriver } from "#src/host/sqlite/sqlite-driver.service";
+import { actorEngine, hostJournal } from "#src/serve/engine/actor-engine.layer";
+import type { ActorHost } from "#src/serve/engine/actor-host.service";
+import { blobHashing } from "./blob-hashing.layer.js";
+import { localFileClients } from "./local-file-clients.layer.js";
+
+const fileHomes = (directory: string): Layer.Layer<LocalBlobHomes, never, FileSystem.FileSystem | Path.Path> =>
+  Layer.unwrap(Effect.map(Path.Path, (path) => LocalBlobHomes.layer(path.join(directory, "files-home")))).pipe(
+    Layer.provide(blobHashing),
+    Layer.provide(SecureRandom.layerWebCrypto),
+    Layer.provide(SqliteDriver.layerNode),
+  );
+
+type LocalActorEngineServices = ActorHost | ActorJournal | ActorRegistry | Layer.Success<typeof localFileClients>;
+
+const localActorEngine = (
+  directory: string,
+): Layer.Layer<LocalActorEngineServices, never, FileSystem.FileSystem | Path.Path> => {
+  const engine = hostJournal.pipe(Layer.provideMerge(actorEngine(directory)), Layer.provide(fileHomes(directory)));
+
+  return localFileClients.pipe(Layer.provideMerge(engine));
+};
+
+export { fileHomes, localActorEngine };
+
+export type { LocalActorEngineServices };

package/src/runtime/local-engine.layer.ts

@@ -0,0 +1,37 @@
+import { Layer } from "effect";
+
+import { JobComputers } from "#src/host/computer/job-computers.service";
+import { hostJournal, providedHandlers } from "#src/serve/engine/actor-engine.layer";
+import type { ActorHost } from "#src/serve/engine/actor-host.service";
+import type { LocalEnvironments } from "#src/serve/environment/local-environments.service";
+import { localEnvironments } from "./local-environments.layer.js";
+import type { LocalOptions } from "./local-environments.layer.js";
+import { localFileClients } from "./local-file-clients.layer.js";
+import type { ComputerNeeds } from "./local-job-runtime.layer.js";
+
+/**
+ * The local engine `Akter.local` runs: the data directory's environments behind one switching host, with the
+ * journal, the file clients, the registry of the handlers it is given, and, with `AKTER_LOCAL_COMPUTERS` on, the
+ * computers of the store it serves, which the app's jobs reach through the same `JobComputers` that `Akter.jobs` gives
+ * them and its `<Actor>/computer/*` RPCs reach directly.
+ */
+const localEngine = (
+  options: LocalOptions,
+): Layer.Layer<
+  | ActorHost
+  | LocalEnvironments
+  | Layer.Success<typeof hostJournal>
+  | Layer.Success<typeof localFileClients>
+  | Layer.Success<typeof providedHandlers>,
+  never,
+  ComputerNeeds
+> =>
+  Layer.mergeAll(localFileClients, hostJournal).pipe(
+    Layer.provideMerge(localEnvironments(options)),
+    Layer.provideMerge(providedHandlers),
+    Layer.provideMerge(JobComputers.layer),
+  );
+
+export { localEngine };
+
+export { offlineEnvironments } from "./local-environments.layer.js";

package/src/runtime/local-environments.layer.ts

@@ -0,0 +1,214 @@
+import { Context, Duration, Effect, Exit, Latch, Layer, Option, Ref, Schedule, Scope, Semaphore, Stream } from "effect";
+import type { FileSystem, Path } from "effect";
+
+import { SqliteDriver } from "#src/host/sqlite/sqlite-driver.service";
+import { ActorHost } from "#src/serve/engine/actor-host.service";
+import { environmentRow, servingRow } from "#src/serve/environment/environment-records.sql";
+import type { EnvironmentRow } from "#src/serve/environment/environment-records.sql";
+import type { Hosting, Store } from "#src/serve/environment/environment-store.sql";
+import { LocalEnvironments } from "#src/serve/environment/local-environments.service";
+import { takePending } from "#src/serve/environment/snapshot-operations.sql";
+import { cutOf, openEnvironment } from "./hosted-environment.layer.js";
+import type { EngineContext, EnvironmentOpening, HostedEnvironment } from "./hosted-environment.layer.js";
+import { computersBinder } from "./local-job-runtime.layer.js";
+import type { BinderNeeds } from "./local-job-runtime.layer.js";
+
+interface LocalOptions {
+  /** The data directory, `.akter` for `akter dev`. */
+  readonly directory: string;
+  /**
+   * Serve this environment of the data directory, such as a branch to call before promoting it, instead of the one
+   * promoted to serve. It stays quiet until it is promoted.
+   */
+  readonly environment?: string | undefined;
+}
+
+type Needs = FileSystem.FileSystem | Path.Path | SqliteDriver;
+
+/** How often the engine reads the record, for what `akter dev environments` and `snapshots` changed in another process. */
+const watchEvery: Duration.Input = "1 second";
+
+/** How long `akter dev snapshots create` waits for the engine serving the environment to take the snapshot. */
+const settleSeconds = 30;
+
+const settleWithin = Duration.seconds(settleSeconds);
+
+const quietFlag = 1;
+
+const oneAtATime = 1;
+
+type Host = ActorHost["Service"];
+
+/**
+ * An actor host that answers each call with whichever host `current` gives at that moment, so the local engine can
+ * switch the environment it serves, as a promote does, while the server and its clients stay as they are.
+ */
+const switchingHost = (current: Effect.Effect<Host>): Host => ({
+  command: (call) => Effect.flatMap(current, (host) => host.command(call)),
+  coveredSince: (request) => Effect.flatMap(current, (host) => host.coveredSince(request)),
+  create: (call) => Effect.flatMap(current, (host) => host.create(call)),
+  currentFiles: (address) => Effect.flatMap(current, (host) => host.currentFiles(address)),
+  drain: Effect.flatMap(current, (host) => host.drain),
+  erase: (address) =>
+    Effect.flatMap(current, (host) =>
+      Option.match(Option.fromNullishOr(host.erase), {
+        onNone: () => Effect.die("the local engine has no actor erasure"),
+        onSome: (erase) => erase(address),
+      }),
+    ),
+  files: (address) => Effect.flatMap(current, (host) => host.files(address)),
+  fork: (call) => Effect.flatMap(current, (host) => host.fork(call)),
+  history: (request) => Effect.flatMap(current, (host) => host.history(request)),
+  prepareFiles: (address) => Effect.flatMap(current, (host) => host.prepareFiles(address)),
+  query: (call) => Effect.flatMap(current, (host) => host.query(call)),
+  state: (address) => Stream.unwrap(Effect.map(current, (host) => host.state(address))),
+  step: (request) => Effect.flatMap(current, (host) => host.step(request)),
+  steps: (request) => Effect.flatMap(current, (host) => host.steps(request)),
+  subscribe: (call) => Stream.unwrap(Effect.map(current, (host) => host.subscribe(call))),
+  warm: (address) => Effect.flatMap(current, (host) => host.warm(address)),
+});
+
+interface Switcher {
+  /** Points the app's job computers at the served environment's store: its `computers` directory. */
+  readonly bindComputers: (store: string) => Effect.Effect<void>;
+  readonly context: EngineContext;
+  readonly current: Ref.Ref<HostedEnvironment>;
+  /** Closed while the engine switches environments, so a call waits for the next one instead of the closing one. */
+  readonly ready: Latch.Latch;
+  readonly pinned: Option.Option<string>;
+  readonly store: Store;
+}
+
+const hostingOf = (
+  { context, store }: Pick<Switcher, "context" | "store">,
+  row: EnvironmentRow,
+): EnvironmentOpening => ({
+  context,
+  name: row.name,
+  quiet: row.quiet,
+  store: store.path.resolve(store.directory, row.directory),
+});
+
+// Serves `row`'s environment instead. The one served now closes first, so its jobs stop before the next one resumes
+// Them from its own journal.
+const switchTo = Effect.fnUntraced(function* switchTo(switcher: Switcher, row: EnvironmentRow) {
+  const before = yield* Ref.get(switcher.current);
+
+  yield* switcher.ready.close;
+  yield* Scope.close(before.scope, Exit.void);
+
+  const next = yield* openEnvironment(hostingOf(switcher, row));
+
+  yield* switcher.bindComputers(next.store);
+  yield* Ref.set(switcher.current, next);
+  yield* switcher.ready.open;
+});
+
+const quietAs = (gate: Latch.Latch, row: EnvironmentRow): Effect.Effect<boolean> => {
+  if (row.quiet === quietFlag) {
+    return gate.close;
+  }
+
+  return gate.open;
+};
+
+/** The environment the record says this engine serves: the pinned one, or the one promoted to serve, while Ready. */
+const servedRow = Effect.fnUntraced(function* servedRow({ pinned, store }: Pick<Switcher, "pinned" | "store">) {
+  const serving = yield* servingRow(store);
+  const wanted = Option.getOrElse(pinned, () => serving.environment);
+  const found = yield* environmentRow({ name: wanted, sql: store.sql });
+
+  return Option.filter(found, (row) => row.status === "Ready");
+});
+
+/**
+ * Applies the record: serves the environment it names (the pinned one, or the one promoted to serve), holds its
+ * actors' upkeep while it is quiet and runs it once it isn't, and takes its pending snapshots.
+ */
+const applied = Effect.fnUntraced(function* applied(switcher: Switcher) {
+  const { store } = switcher;
+  const row = yield* servedRow(switcher);
+  const hosted = yield* Ref.get(switcher.current);
+
+  if (Option.isSome(row) && row.value.name !== hosted.name) {
+    yield* switchTo(switcher, row.value);
+  }
+
+  const current = yield* Ref.get(switcher.current);
+
+  yield* Effect.forEach(Option.toArray(row), (now) => quietAs(current.gate, now));
+  yield* takePending({ cut: cutOf(switcher.context)(current), store })(current.name);
+});
+
+const firstHosted = Effect.fnUntraced(function* firstHosted(
+  { context, store }: Pick<Switcher, "context" | "store">,
+  pinned: Option.Option<string>,
+) {
+  const ready = yield* servedRow({ pinned, store });
+  const unknown = Effect.die(`akter dev has no Ready environment ${Option.getOrElse(pinned, () => "")} to serve`);
+  const row = yield* Option.match(ready, { onNone: () => unknown, onSome: Effect.succeed });
+
+  return yield* openEnvironment(hostingOf({ context, store }, row));
+});
+
+const openRecord = (directory: string, hosting: Hosting): Effect.Effect<Store, never, Needs | Scope.Scope> =>
+  Effect.orDie(SqliteDriver.use((driver) => LocalEnvironments.openStore({ directory, hosting, open: driver.open })));
+
+const startSwitcher = Effect.fnUntraced(function* startSwitcher({ directory, environment }: LocalOptions) {
+  const context = yield* Effect.context<Needs>();
+  const bindComputers = yield* computersBinder();
+  const store = yield* openRecord(directory, { apply: Effect.void, settleWithin: Duration.zero });
+  const pinned = Option.fromUndefinedOr(environment);
+  const first = yield* Effect.orDie(firstHosted({ context, store }, pinned));
+
+  yield* bindComputers(first.store);
+
+  const current = yield* Ref.make(first);
+  const ready = yield* Latch.make(true);
+
+  yield* Effect.addFinalizer(() => Effect.flatMap(Ref.get(current), (hosted) => Scope.close(hosted.scope, Exit.void)));
+
+  return { bindComputers, context, current, pinned, ready, store } satisfies Switcher;
+});
+
+const applying = (switcher: Switcher, semaphore: Semaphore.Semaphore): Effect.Effect<void> =>
+  semaphore
+    .withPermits(oneAtATime)(applied(switcher))
+    .pipe(Effect.catchCause((cause) => Effect.logWarning("akter dev could not apply its environments", cause)));
+
+/**
+ * The local engine on a data directory's environments: it serves one of them at a time through one actor host, and
+ * switches to another when a promote makes it serve. `LocalEnvironments` snapshots, branches and promotes them.
+ */
+const localEnvironments = (options: LocalOptions): Layer.Layer<ActorHost | LocalEnvironments, never, BinderNeeds> =>
+  Layer.effectContext(
+    Effect.gen(function* makeLocalEnvironments() {
+      const switcher = yield* startSwitcher(options);
+      const semaphore = yield* Semaphore.make(oneAtATime);
+      const apply = applying(switcher, semaphore);
+      const served = Effect.andThen(switcher.ready.await, Ref.get(switcher.current));
+
+      yield* Effect.forkScoped(Effect.repeat(apply, Schedule.spaced(watchEvery)));
+
+      const environments = LocalEnvironments.on({ ...switcher.store, hosting: { apply, settleWithin: Duration.zero } });
+      const host = switchingHost(Effect.map(served, (hosted) => hosted.host));
+
+      return Context.make(ActorHost, host).pipe(Context.add(LocalEnvironments, environments));
+    }),
+  ).pipe(Layer.provide(SqliteDriver.layerNode));
+
+/**
+ * A data directory's environments without an engine, as the CLI reads them: what it changes, the `akter dev` serving
+ * the directory applies on its next look, and a snapshot is waited for while that engine takes it.
+ */
+const offlineEnvironments = (
+  directory: string,
+): Layer.Layer<LocalEnvironments, never, FileSystem.FileSystem | Path.Path> =>
+  Layer.effect(
+    LocalEnvironments,
+    Effect.map(openRecord(directory, { apply: Effect.void, settleWithin }), LocalEnvironments.on),
+  ).pipe(Layer.provide(SqliteDriver.layerNode));
+
+export { localEnvironments, offlineEnvironments };
+
+export type { LocalOptions };