alchemy 2.0.0-beta.73 → 2.0.0-beta.75

package/src/Runtime/Bootstrap/AppRunner.ts

@@ -0,0 +1,50 @@
+/**
+ * Process bootstrap for `AWS.AppRunner.Service` containers. The generated
+ * entry imports this module and the user's `main`, nothing else — see
+ * {@link ./Process.ts} for why.
+ */
+import * as Credentials from "@distilled.cloud/aws/Credentials";
+import * as Region from "@distilled.cloud/aws/Region";
+import { BunServices } from "@effect/platform-bun";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { BunHttpServer } from "../../Http.ts";
+import {
+  entrypointLayer,
+  resolveProgram,
+  runProcess,
+  stackFromEnv,
+} from "./Process.ts";
+
+/** Serve the bundled program with a Bun HTTP server on the injected `PORT`. */
+export const bootstrap = (entrypoint: unknown): Promise<void> => {
+  const platform = Layer.mergeAll(
+    BunServices.layer,
+    FetchHttpClient.layer,
+    Logger.layer([Logger.consolePretty()]),
+  );
+
+  const program = resolveProgram("program").pipe(
+    Effect.provide(
+      entrypointLayer(entrypoint).pipe(
+        Layer.provideMerge(stackFromEnv),
+        Layer.provideMerge(Credentials.fromEnv()),
+        Layer.provideMerge(Region.fromEnv()),
+        Layer.provideMerge(BunHttpServer()),
+        Layer.provideMerge(platform),
+        Layer.provideMerge(
+          Layer.succeed(
+            ConfigProvider.ConfigProvider,
+            ConfigProvider.fromEnv(),
+          ),
+        ),
+      ),
+    ),
+    Effect.scoped,
+  );
+
+  return runProcess("App Runner service", program);
+};

package/src/Runtime/Bootstrap/Batch.ts

@@ -0,0 +1,51 @@
+/**
+ * Process bootstrap for `AWS.Batch.JobDefinition` containers. The generated
+ * entry imports this module and the user's `main`, nothing else — see
+ * {@link ./Process.ts} for why.
+ */
+import * as Credentials from "@distilled.cloud/aws/Credentials";
+import * as Region from "@distilled.cloud/aws/Region";
+import { BunServices } from "@effect/platform-bun";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import {
+  entrypointLayer,
+  resolveProgram,
+  runProcess,
+  stackFromEnv,
+} from "./Process.ts";
+
+/**
+ * Run the bundled job to completion: no HTTP server, and the process exits 0
+ * explicitly once the program finishes (Batch waits on the container).
+ */
+export const bootstrap = (entrypoint: unknown): Promise<void> => {
+  const platform = Layer.mergeAll(
+    BunServices.layer,
+    FetchHttpClient.layer,
+    Logger.layer([Logger.consolePretty()]),
+  );
+
+  const program = resolveProgram("program").pipe(
+    Effect.provide(
+      entrypointLayer(entrypoint).pipe(
+        Layer.provideMerge(stackFromEnv),
+        Layer.provideMerge(Credentials.fromEnv()),
+        Layer.provideMerge(Region.fromEnv()),
+        Layer.provideMerge(platform),
+        Layer.provideMerge(
+          Layer.succeed(
+            ConfigProvider.ConfigProvider,
+            ConfigProvider.fromEnv(),
+          ),
+        ),
+      ),
+    ),
+    Effect.scoped,
+  );
+
+  return runProcess("Batch job", program, { exitOnComplete: true });
+};

package/src/Runtime/Bootstrap/CloudflareContainer.ts

@@ -0,0 +1,90 @@
+/**
+ * Process bootstrap core for `Cloudflare.Container` images. The runtime
+ * (`bun` | `node`) is chosen at deploy time, and each is an optional peer,
+ * so the platform-specific layers are supplied by the thin entry modules
+ * {@link ./CloudflareContainerBun.ts} / {@link ./CloudflareContainerNode.ts}
+ * rather than imported here. The generated entry imports one of those and
+ * the user's `main`, nothing else — see {@link ./Process.ts} for why.
+ */
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import { MinimumLogLevel } from "effect/References";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { CloudflareEnvironment } from "../../Cloudflare/CloudflareEnvironment.ts";
+import { reifyBoundConfigProvider } from "../../Runtime.ts";
+import {
+  entrypointLayer,
+  resolveProgram,
+  runProcess,
+  stackConstant,
+} from "./Process.ts";
+
+export interface ContainerBootstrapOptions {
+  /** Stack identity baked in at deploy time. */
+  readonly stack: { readonly name: string; readonly stage: string };
+}
+
+export interface ContainerRuntime {
+  /** `BunServices.layer` / `NodeServices.layer`. */
+  readonly services: Layer.Layer<any>;
+  /** `BunHttpServer()` / `NodeHttpServer()`. */
+  readonly httpServer: Layer.Layer<any, any, any>;
+}
+
+/** Serve the bundled container program on the runtime's HTTP server. */
+export const bootstrapContainer = (
+  runtime: ContainerRuntime,
+  entrypoint: unknown,
+  options: ContainerBootstrapOptions,
+): Promise<void> => {
+  const platform = Layer.mergeAll(
+    runtime.services,
+    FetchHttpClient.layer,
+    // TODO(sam): wire this up to telemetry more directly
+    Logger.layer([Logger.consolePretty()]),
+  );
+
+  const program = resolveProgram("default", { telemetry: true }).pipe(
+    Effect.provide(
+      entrypointLayer(entrypoint).pipe(
+        Layer.provideMerge(
+          stackConstant(options.stack.name, options.stack.stage),
+        ),
+        Layer.provideMerge(runtime.httpServer),
+        // Capability bindings that talk to Cloudflare's HTTP API from inside
+        // the container (e.g. R2/KV/Queue `*Http` bindings) resolve their
+        // account via `CloudflareEnvironment` at runtime, exactly like the
+        // Worker bridge does (the service value is an `Effect` of the
+        // resolved credentials). The per-operation account/token are read
+        // from the container's env (the bound token outputs), so an absent
+        // account id here is harmless.
+        Layer.provideMerge(
+          Layer.succeed(
+            CloudflareEnvironment,
+            Effect.succeed({
+              account: process.env.ALCHEMY_CLOUDFLARE_ACCOUNT_ID,
+            }) as any,
+          ),
+        ),
+        Layer.provideMerge(platform),
+        Layer.provideMerge(
+          Layer.succeed(
+            ConfigProvider.ConfigProvider,
+            // Auto-bound `Config` values arrive in the env as
+            // `{"_tag":"Redacted","value":...}` markers; reify them so a
+            // `Config` re-read inside a handler decodes the raw source value.
+            reifyBoundConfigProvider(ConfigProvider.fromEnv(), process.env),
+          ),
+        ),
+        Layer.provideMerge(
+          Layer.succeed(MinimumLogLevel, process.env.DEBUG ? "Debug" : "Info"),
+        ),
+      ),
+    ),
+    Effect.scoped,
+  );
+
+  return runProcess("Container", program);
+};

package/src/Runtime/Bootstrap/CloudflareContainerBun.ts

@@ -0,0 +1,17 @@
+/** `Cloudflare.Container` bootstrap on the bun runtime. */
+import { BunServices } from "@effect/platform-bun";
+import { BunHttpServer } from "../../Http.ts";
+import {
+  bootstrapContainer,
+  type ContainerBootstrapOptions,
+} from "./CloudflareContainer.ts";
+
+export const bootstrap = (
+  entrypoint: unknown,
+  options: ContainerBootstrapOptions,
+): Promise<void> =>
+  bootstrapContainer(
+    { services: BunServices.layer, httpServer: BunHttpServer() },
+    entrypoint,
+    options,
+  );

package/src/Runtime/Bootstrap/CloudflareContainerNode.ts

@@ -0,0 +1,17 @@
+/** `Cloudflare.Container` bootstrap on the node runtime. */
+import { NodeServices } from "@effect/platform-node";
+import { NodeHttpServer } from "../../Http.ts";
+import {
+  bootstrapContainer,
+  type ContainerBootstrapOptions,
+} from "./CloudflareContainer.ts";
+
+export const bootstrap = (
+  entrypoint: unknown,
+  options: ContainerBootstrapOptions,
+): Promise<void> =>
+  bootstrapContainer(
+    { services: NodeServices.layer, httpServer: NodeHttpServer() },
+    entrypoint,
+    options,
+  );

package/src/Runtime/Bootstrap/Docker.ts

@@ -0,0 +1,51 @@
+/**
+ * Process bootstrap for `Docker.Service` (a bun process serving the
+ * bundled program). The generated entry imports this module and the user's
+ * `main`, nothing else — see {@link ./Process.ts} for why.
+ */
+import { BunServices } from "@effect/platform-bun";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { BunHttpServer } from "../../Http.ts";
+import { reifyBoundConfigProvider } from "../../Runtime.ts";
+import {
+  entrypointLayer,
+  resolveProgram,
+  runProcess,
+  stackFromEnv,
+} from "./Process.ts";
+
+/**
+ * Resolve the bundled program (the runners registered via `host.run` /
+ * serve) and run it with a Bun HTTP server bound to `PORT`, so the returned
+ * `{ fetch }` handler is actually served and `host.run` loops stay alive.
+ */
+export const bootstrap = (entrypoint: unknown): Promise<void> => {
+  const platform = Layer.mergeAll(
+    BunServices.layer,
+    FetchHttpClient.layer,
+    Logger.layer([Logger.consolePretty()]),
+  );
+
+  const program = resolveProgram("program").pipe(
+    Effect.provide(
+      entrypointLayer(entrypoint).pipe(
+        Layer.provideMerge(stackFromEnv),
+        Layer.provideMerge(BunHttpServer()),
+        Layer.provideMerge(platform),
+        Layer.provideMerge(
+          Layer.succeed(
+            ConfigProvider.ConfigProvider,
+            reifyBoundConfigProvider(ConfigProvider.fromEnv(), process.env),
+          ),
+        ),
+      ),
+    ),
+    Effect.scoped,
+  );
+
+  return runProcess("Docker service", program);
+};

package/src/Runtime/Bootstrap/Ec2.ts

@@ -0,0 +1,52 @@
+/**
+ * Process bootstrap for the hosted `AWS.EC2.Instance` program (a systemd
+ * unit running bun). The generated entry imports this module and the user's
+ * `main`, nothing else — see {@link ./Process.ts} for why.
+ */
+import * as Credentials from "@distilled.cloud/aws/Credentials";
+import * as Region from "@distilled.cloud/aws/Region";
+import { BunServices } from "@effect/platform-bun";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { BunHttpServer } from "../../Http.ts";
+import { reifyBoundConfigProvider } from "../../Runtime.ts";
+import {
+  entrypointLayer,
+  resolveProgram,
+  runProcess,
+  stackFromEnv,
+} from "./Process.ts";
+
+/** Serve the bundled program with a Bun HTTP server on the instance's `PORT`. */
+export const bootstrap = (entrypoint: unknown): Promise<void> => {
+  const platform = Layer.mergeAll(
+    BunServices.layer,
+    FetchHttpClient.layer,
+    Logger.layer([Logger.consolePretty()]),
+  );
+
+  const program = resolveProgram("program", { telemetry: true }).pipe(
+    Effect.provide(
+      entrypointLayer(entrypoint).pipe(
+        Layer.provideMerge(stackFromEnv),
+        // The instance profile: credentials come from IMDS, not the env.
+        Layer.provideMerge(Credentials.fromChain()),
+        Layer.provideMerge(Region.fromEnv()),
+        Layer.provideMerge(BunHttpServer()),
+        Layer.provideMerge(platform),
+        Layer.provideMerge(
+          Layer.succeed(
+            ConfigProvider.ConfigProvider,
+            reifyBoundConfigProvider(ConfigProvider.fromEnv(), process.env),
+          ),
+        ),
+      ),
+    ),
+    Effect.scoped,
+  );
+
+  return runProcess("Instance", program);
+};

package/src/Runtime/Bootstrap/Ecs.ts

@@ -0,0 +1,66 @@
+/**
+ * Process bootstrap for `AWS.ECS.Task` / `AWS.ECS.Service` containers. The
+ * generated entry imports this module and the user's `main`, nothing else —
+ * see {@link ./Process.ts} for why.
+ */
+import * as Credentials from "@distilled.cloud/aws/Credentials";
+import * as Endpoint from "@distilled.cloud/aws/Endpoint";
+import * as Region from "@distilled.cloud/aws/Region";
+import { BunServices } from "@effect/platform-bun";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { BunHttpServer } from "../../Http.ts";
+import { reifyBoundConfigProvider } from "../../Runtime.ts";
+import {
+  entrypointLayer,
+  resolveProgram,
+  runProcess,
+  stackFromEnv,
+} from "./Process.ts";
+
+/**
+ * Resolve the bundled program (the runners registered via `host.run` /
+ * serve) and run it with a Bun HTTP server bound to `PORT`, so a returned
+ * `{ fetch }` handler is actually served and `host.run` loops stay alive. A
+ * pure one-shot `{ run }` program completes and the process exits 0.
+ */
+export const bootstrap = (entrypoint: unknown): Promise<void> => {
+  const platform = Layer.mergeAll(
+    BunServices.layer,
+    FetchHttpClient.layer,
+    Logger.layer([Logger.consolePretty()]),
+  );
+
+  const program = resolveProgram("program", { telemetry: true }).pipe(
+    Effect.provide(
+      entrypointLayer(entrypoint).pipe(
+        Layer.provideMerge(stackFromEnv),
+        // Full provider chain, not fromEnv: Fargate tasks receive credentials
+        // from the container-credentials endpoint
+        // (AWS_CONTAINER_CREDENTIALS_RELATIVE_URI), not environment variables.
+        Layer.provideMerge(Credentials.fromChain()),
+        Layer.provideMerge(Region.fromEnv()),
+        // AWS_ENDPOINT_URL is the LocalStack-standard override injected by
+        // local emulators (floci) into task containers — without it, runtime
+        // bindings in `alchemy dev` would call REAL AWS with dummy
+        // credentials. Resolves undefined when unset, so live deploys are
+        // unaffected.
+        Layer.provideMerge(Endpoint.fromEnv()),
+        Layer.provideMerge(BunHttpServer()),
+        Layer.provideMerge(platform),
+        Layer.provideMerge(
+          Layer.succeed(
+            ConfigProvider.ConfigProvider,
+            reifyBoundConfigProvider(ConfigProvider.fromEnv(), process.env),
+          ),
+        ),
+      ),
+    ),
+    Effect.scoped,
+  );
+
+  return runProcess("Task", program);
+};

package/src/Runtime/Bootstrap/Fly.ts

@@ -0,0 +1,52 @@
+/**
+ * Process bootstrap for `Fly.Service` and `Fly.Sprite` (a Node process
+ * serving the bundled program). The generated entry imports this module
+ * and the user's `main`, nothing else — see {@link ./Process.ts} for why.
+ */
+import { NodeServices } from "@effect/platform-node";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { NodeHttpServer } from "../../Http.ts";
+import { reifyBoundConfigProvider } from "../../Runtime.ts";
+import {
+  entrypointLayer,
+  resolveProgram,
+  runProcess,
+  stackFromEnv,
+} from "./Process.ts";
+
+/**
+ * Resolve the bundled program (the runners registered via `host.run` /
+ * serve) and run it with a Node HTTP server bound to `PORT`, so the
+ * returned `{ fetch }` handler is actually served and `host.run` loops
+ * stay alive.
+ */
+export const bootstrap = (entrypoint: unknown): Promise<void> => {
+  const platform = Layer.mergeAll(
+    NodeServices.layer,
+    FetchHttpClient.layer,
+    Logger.layer([Logger.consolePretty()]),
+  );
+
+  const program = resolveProgram("program").pipe(
+    Effect.provide(
+      entrypointLayer(entrypoint).pipe(
+        Layer.provideMerge(stackFromEnv),
+        Layer.provideMerge(NodeHttpServer({ hostname: "0.0.0.0" })),
+        Layer.provideMerge(platform),
+        Layer.provideMerge(
+          Layer.succeed(
+            ConfigProvider.ConfigProvider,
+            reifyBoundConfigProvider(ConfigProvider.fromEnv(), process.env),
+          ),
+        ),
+      ),
+    ),
+    Effect.scoped,
+  );
+
+  return runProcess("Fly service", program);
+};

package/src/Runtime/Bootstrap/Hetzner.ts

@@ -0,0 +1,52 @@
+/**
+ * Process bootstrap for `Hetzner.Service` (a Node process serving the
+ * bundled program). The generated entry imports this module and the user's
+ * `main`, nothing else — see {@link ./Process.ts} for why.
+ */
+import { NodeServices } from "@effect/platform-node";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import { NodeHttpServer } from "../../Http.ts";
+import { reifyBoundConfigProvider } from "../../Runtime.ts";
+import {
+  entrypointLayer,
+  resolveProgram,
+  runProcess,
+  stackFromEnv,
+} from "./Process.ts";
+
+/**
+ * Resolve the bundled program (the runners registered via `host.run` /
+ * serve) and run it with a Node HTTP server bound to `PORT`, so the
+ * returned `{ fetch }` handler is actually served and `host.run` loops
+ * stay alive.
+ */
+export const bootstrap = (entrypoint: unknown): Promise<void> => {
+  const platform = Layer.mergeAll(
+    NodeServices.layer,
+    FetchHttpClient.layer,
+    Logger.layer([Logger.consolePretty()]),
+  );
+
+  const program = resolveProgram("program").pipe(
+    Effect.provide(
+      entrypointLayer(entrypoint).pipe(
+        Layer.provideMerge(stackFromEnv),
+        Layer.provideMerge(NodeHttpServer({ hostname: "0.0.0.0" })),
+        Layer.provideMerge(platform),
+        Layer.provideMerge(
+          Layer.succeed(
+            ConfigProvider.ConfigProvider,
+            reifyBoundConfigProvider(ConfigProvider.fromEnv(), process.env),
+          ),
+        ),
+      ),
+    ),
+    Effect.scoped,
+  );
+
+  return runProcess("Hetzner service", program);
+};

package/src/Runtime/Bootstrap/Lambda.ts

@@ -0,0 +1,100 @@
+/**
+ * Bootstrap for `AWS.Lambda.Function` (zip, Node runtime). The generated
+ * entry imports this module and the user's `main`, and re-exports the
+ * handler this returns — see {@link ./Process.ts} for why the entry is a
+ * shim.
+ */
+import * as Credentials from "@distilled.cloud/aws/Credentials";
+import * as Endpoint from "@distilled.cloud/aws/Endpoint";
+import * as Region from "@distilled.cloud/aws/Region";
+import { layer as nodeServicesLayer } from "@effect/platform-node/NodeServices";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import { MinimumLogLevel } from "effect/References";
+import * as Scope from "effect/Scope";
+import { layer as fetchHttpClientLayer } from "effect/unstable/http/FetchHttpClient";
+import { registerLambdaExtension } from "../../AWS/Lambda/RuntimeExtension.ts";
+import { reifyBoundConfigProvider } from "../../Runtime.ts";
+import { entrypointLayer, entrypointTag, stackFromEnv } from "./Process.ts";
+
+/**
+ * Build the sandbox-lifetime layer stack and return the Lambda handler the
+ * bundled function registered.
+ *
+ * The layer build lives under an instance scope (not a transient
+ * `Effect.provide`/`Effect.scoped` region) so services and init-level
+ * finalizers live for the sandbox and are released at Shutdown — Lambda's
+ * SIGTERM phase, which the internal extension registered here buys us
+ * (without any registered extension the sandbox is killed with no signal at
+ * all). Each invocation still gets its own request scope from the handler
+ * dispatch.
+ */
+export const bootstrap = async (entrypoint: unknown): Promise<unknown> => {
+  await registerLambdaExtension();
+
+  const instanceScope = Scope.makeUnsafe();
+
+  const platform = Layer.mergeAll(
+    nodeServicesLayer,
+    fetchHttpClientLayer,
+    // TODO(sam): wire this up to telemetry more directly
+    Logger.layer([Logger.consolePretty()]),
+  );
+
+  const entryLayer = entrypointLayer(entrypoint).pipe(
+    Layer.provideMerge(stackFromEnv),
+    Layer.provideMerge(Credentials.fromEnv()),
+    Layer.provideMerge(Region.fromEnv()),
+    // AWS_ENDPOINT_URL is the LocalStack-standard override injected by local
+    // emulators (floci) into the Lambda container — without it, runtime
+    // bindings in `alchemy dev` would call REAL AWS with dummy credentials.
+    // Resolves undefined when unset, so live deploys are unaffected.
+    Layer.provideMerge(Endpoint.fromEnv()),
+    Layer.provideMerge(platform),
+    Layer.provideMerge(
+      Layer.succeed(
+        ConfigProvider.ConfigProvider,
+        // Auto-bound `Config` values arrive in the env as
+        // `{"_tag":"Redacted","value":...}` markers; reify them so a `Config`
+        // re-read inside a handler decodes the raw source value.
+        reifyBoundConfigProvider(ConfigProvider.fromEnv(), process.env),
+      ),
+    ),
+    Layer.provideMerge(
+      Layer.succeed(MinimumLogLevel, process.env.DEBUG ? "Debug" : "Info"),
+    ),
+  );
+
+  const handlerEffect: Effect.Effect<unknown, unknown> = Layer.buildWithScope(
+    entryLayer,
+    instanceScope,
+  ).pipe(
+    Effect.flatMap((context) =>
+      entrypointTag.pipe(
+        Effect.flatMap((func) => func.RuntimeContext.exports),
+        Effect.flatMap((exports: any) => exports.handler),
+        Effect.provideContext(context),
+      ),
+    ),
+    Scope.provide(instanceScope),
+  );
+
+  const handler = await Effect.runPromise(handlerEffect);
+
+  // Lambda's Shutdown phase: close the instance scope so init-level
+  // finalizers run, then exit inside the 500 ms budget. SIGKILL follows if
+  // we overstay, so finalizers must be fast and best-effort.
+  process.on("SIGTERM", () => {
+    console.log("[alchemy] SIGTERM — closing instance scope");
+    Effect.runPromise(Scope.close(instanceScope, Exit.void))
+      .catch((error) =>
+        console.error("[alchemy] shutdown finalizers failed", error),
+      )
+      .finally(() => process.exit(0));
+  });
+
+  return handler;
+};

package/src/Runtime/Bootstrap/Microvm.ts

@@ -0,0 +1,68 @@
+/**
+ * Process bootstrap core for `AWS.Lambda.MicrovmImage` images. The runtime
+ * (`bun` | `node`) is chosen at deploy time, and each is an optional peer,
+ * so the platform-specific layers are supplied by the thin entry modules
+ * {@link ./MicrovmBun.ts} / {@link ./MicrovmNode.ts} rather than imported
+ * here. The generated entry imports one of those and the user's `main`,
+ * nothing else — see {@link ./Process.ts} for why.
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+import { MinimumLogLevel } from "effect/References";
+import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
+import {
+  entrypointLayer,
+  resolveProgram,
+  runProcess,
+  stackConstant,
+} from "./Process.ts";
+
+export interface MicrovmBootstrapOptions {
+  /** Port to serve on when the VM does not inject `PORT`. */
+  readonly port: number;
+  /** Stack identity baked in at deploy time. */
+  readonly stack: { readonly name: string; readonly stage: string };
+}
+
+export interface MicrovmRuntime {
+  /** `BunServices.layer` / `NodeServices.layer`. */
+  readonly services: Layer.Layer<any>;
+  /** `BunHttpServer()` / `NodeHttpServer()`; both listen on `PORT`. */
+  readonly httpServer: Layer.Layer<any, any, any>;
+}
+
+/** Serve the bundled in-VM program on the runtime's HTTP server. */
+export const bootstrapMicrovm = (
+  runtime: MicrovmRuntime,
+  entrypoint: unknown,
+  options: MicrovmBootstrapOptions,
+): Promise<void> => {
+  // The HTTP server listens on `PORT`; default it to the image's port when
+  // the VM does not inject one.
+  process.env.PORT ??= String(options.port);
+
+  const platform = Layer.mergeAll(
+    runtime.services,
+    FetchHttpClient.layer,
+    Logger.layer([Logger.consolePretty()]),
+  );
+
+  const program = resolveProgram("default", { telemetry: true }).pipe(
+    Effect.provide(
+      entrypointLayer(entrypoint).pipe(
+        Layer.provideMerge(
+          stackConstant(options.stack.name, options.stack.stage),
+        ),
+        Layer.provideMerge(runtime.httpServer),
+        Layer.provideMerge(platform),
+        Layer.provideMerge(
+          Layer.succeed(MinimumLogLevel, process.env.DEBUG ? "Debug" : "Info"),
+        ),
+      ),
+    ),
+    Effect.scoped,
+  );
+
+  return runProcess(`MicroVM (port ${process.env.PORT})`, program);
+};