@alchemy.run/modal 0.0.0 → 2.0.0-beta.87

package/src/ReadWriteQueue.ts

@@ -0,0 +1,45 @@
+import * as Binding from "alchemy/Binding";
+import type * as Effect from "effect/Effect";
+import type { Queue } from "./Queue.ts";
+import type { ReadWriteQueueClient } from "./QueueClient.ts";
+
+export type { ReadWriteQueueClient } from "./QueueClient.ts";
+
+/**
+ * Put and take items on a Modal Queue from any runtime. Items are JSON.
+ *
+ * ### Bind a queue
+ * **Example:** From a Cloudflare Worker
+ * ```typescript
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Jobs } from "./Storage.ts";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const queue = yield* Modal.ReadWriteQueue(Jobs);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         yield* queue.put({ n: 1 });
+ *         const items = yield* queue.take({ count: 10 });
+ *         return yield* HttpServerResponse.json(items);
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Modal.ReadWriteQueueHttp)),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Queue
+ */
+export interface ReadWriteQueue extends Binding.Service<
+  ReadWriteQueue,
+  "Modal.ReadWriteQueue",
+  (queue: Queue) => Effect.Effect<ReadWriteQueueClient>
+> {}
+
+export const ReadWriteQueue = Binding.Service<ReadWriteQueue>("Modal.ReadWriteQueue");

package/src/ReadWriteQueueHttp.ts

@@ -0,0 +1,27 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { makeModalBinding } from "./BindingHttp.ts";
+import type { Queue } from "./Queue.ts";
+import { QueueOps, makeReadWriteQueueClient } from "./QueueClient.ts";
+import { ReadWriteQueue } from "./ReadWriteQueue.ts";
+
+/**
+ * {@link ReadWriteQueue} over Modal's API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `contributor` role on the queue's environment.
+ *
+ * @layer
+ * @product Queue
+ * @provides Modal.ReadWriteQueue
+ */
+export const ReadWriteQueueHttp = Layer.effect(
+  ReadWriteQueue,
+  makeModalBinding({
+    tag: "Modal.ReadWriteQueue",
+    operations: QueueOps,
+    role: "contributor",
+    make: Effect.fn(function* (queue: Queue, ops) {
+      const queueId = yield* queue.queueId;
+      return makeReadWriteQueueClient(queueId, ops);
+    }),
+  }),
+);

package/src/ReadWriteVolume.ts

@@ -0,0 +1,45 @@
+import * as Binding from "alchemy/Binding";
+import type * as Effect from "effect/Effect";
+import type { Volume } from "./Volume.ts";
+import type { ReadWriteVolumeClient } from "./VolumeClient.ts";
+
+export type { ReadWriteVolumeClient } from "./VolumeClient.ts";
+
+/**
+ * Read and write a Modal Volume's files from any runtime without mounting it.
+ *
+ * ### Bind a volume
+ * **Example:** ReadWrite from a Cloudflare Worker
+ * ```typescript
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Workspace } from "./Storage.ts";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const volume = yield* Modal.ReadWriteVolume(Workspace);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         yield* volume.writeFile("/hello.txt", "hello");
+ *         const text = yield* volume.readFileString("/hello.txt");
+ *         return HttpServerResponse.text(text);
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Modal.ReadWriteVolumeHttp)),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Volume
+ */
+export interface ReadWriteVolume extends Binding.Service<
+  ReadWriteVolume,
+  "Modal.ReadWriteVolume",
+  (volume: Volume) => Effect.Effect<ReadWriteVolumeClient>
+> {}
+
+export const ReadWriteVolume = Binding.Service<ReadWriteVolume>("Modal.ReadWriteVolume");

package/src/ReadWriteVolumeHttp.ts

@@ -0,0 +1,28 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { makeModalBinding } from "./BindingHttp.ts";
+import { ReadWriteVolume } from "./ReadWriteVolume.ts";
+import type { Volume } from "./Volume.ts";
+import { makeReadWriteVolumeClient } from "./VolumeClient.ts";
+import { VolumeFileOps } from "./VolumeFiles.ts";
+
+/**
+ * {@link ReadWriteVolume} over Modal's volume API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `contributor` role on the volume's environment.
+ *
+ * @layer
+ * @product Volume
+ * @provides Modal.ReadWriteVolume
+ */
+export const ReadWriteVolumeHttp = Layer.effect(
+  ReadWriteVolume,
+  makeModalBinding({
+    tag: "Modal.ReadWriteVolume",
+    operations: VolumeFileOps,
+    role: "contributor",
+    make: Effect.fn(function* (volume: Volume, ops) {
+      const volumeId = yield* volume.volumeId;
+      return makeReadWriteVolumeClient(volumeId, ops);
+    }),
+  }),
+);

package/src/RuntimeOwner.ts

@@ -0,0 +1,111 @@
+import * as Binding from "alchemy/Binding";
+import * as Output from "alchemy/Output";
+import { CurrentRuntimeContext } from "alchemy/RuntimeContext";
+import { Stack } from "alchemy/Stack";
+import { Stage } from "alchemy/Stage";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+
+/**
+ * Who created an object at run time: the stack, stage and binding host
+ * (`alchemy::stack`, `alchemy::stage`, `alchemy::id`).
+ *
+ * The `Create*` bindings mark every object they create with it, so the
+ * objects can be found and cleaned up. Destroying the stack does not delete
+ * them. Modal tags sandboxes, so a sandbox carries the three keys as tags;
+ * volumes, dicts, queues and secrets have only a name, so theirs starts with
+ * {@link runtimePrefix}, and `alchemy nuke` deletes them by it.
+ */
+export interface RuntimeOwner {
+  readonly stack: string;
+  readonly stage: string;
+  readonly id: string;
+}
+
+/** The owner as Modal sandbox tags. */
+export const runtimeTags = (owner: RuntimeOwner): Record<string, string> => ({
+  "alchemy::stack": owner.stack,
+  "alchemy::stage": owner.stage,
+  "alchemy::id": owner.id,
+});
+
+const toLabel = (value: string) =>
+  value
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+
+/** FNV-1a, 32 bits: a short, stable digest of the full identity. */
+const digest = (value: string) => {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+};
+
+/**
+ * The name prefix of objects that carry only a name:
+ * `alc-<stack-stage-id>-<digest>`, the identity readable and cut to 16
+ * characters, then a digest of all three. An object `name` becomes
+ * `<prefix>-<name>`. The `alc-` marker is how `alchemy nuke` recognizes them.
+ */
+export const runtimePrefix = (owner: RuntimeOwner): string => {
+  const readable =
+    toLabel(`${owner.stack}-${owner.stage}-${owner.id}`).slice(0, 16).replace(/-+$/, "") || "x";
+  return `alc-${readable}-${digest(`${owner.stack}/${owner.stage}/${owner.id}`)}`;
+};
+
+/** Whether `name` carries some owner's {@link runtimePrefix}. */
+export const isRuntimeName = (name: string | undefined): boolean =>
+  name !== undefined && /^alc-[a-z0-9](?:[a-z0-9-]*[a-z0-9])?-[0-9a-f]{8}-./.test(name);
+
+/** The name an object gets: `<prefix>-<name>` with an owner, `name` without one. */
+export const ownedName = (owner: RuntimeOwner | undefined, name: string) =>
+  owner === undefined ? name : `${runtimePrefix(owner)}-${name}`;
+
+/** An owned object's name without the prefix, or `undefined` when another owner's. */
+export const unownedName = (owner: RuntimeOwner | undefined, name: string) => {
+  if (owner === undefined) return name;
+  const prefix = `${runtimePrefix(owner)}-`;
+  return name.startsWith(prefix) ? name.slice(prefix.length) : undefined;
+};
+
+const ENV = {
+  stack: "ALCHEMY_MODAL_OWNER_STACK",
+  stage: "ALCHEMY_MODAL_OWNER_STAGE",
+  id: "ALCHEMY_MODAL_OWNER_ID",
+} as const;
+
+/**
+ * The owner a `Create*` binding marks its objects with. Yield it while the
+ * binding's layer is built and call the result inside the binding: at deploy
+ * it binds the host's identity into the host's env; at run time its Effect
+ * reads it back. Without a host (a script or an Action) there is no owner.
+ */
+export const RuntimeOwnerOf = Effect.fn(function* () {
+  const runtime = yield* CurrentRuntimeContext;
+  if (runtime === undefined) return Effect.succeed<RuntimeOwner | undefined>(undefined);
+  if (!globalThis.__ALCHEMY_RUNTIME__) {
+    const host = yield* Binding.Host;
+    // The deploying stack and stage, read without requiring them, so the
+    // binding's `make` needs nothing a script or an Action lacks.
+    const stack = Option.getOrUndefined(yield* Effect.serviceOption(Stack));
+    const stage = Option.getOrUndefined(yield* Effect.serviceOption(Stage));
+    if (host !== undefined && stack !== undefined && stage !== undefined) {
+      yield* runtime.set(ENV.stack, Output.literal(stack.name));
+      yield* runtime.set(ENV.stage, Output.literal(stage));
+      yield* runtime.set(ENV.id, Output.literal(host.LogicalId));
+    }
+  }
+  return Effect.gen(function* () {
+    const stack = yield* runtime.get<string>(ENV.stack);
+    const stage = yield* runtime.get<string>(ENV.stage);
+    const id = yield* runtime.get<string>(ENV.id);
+    return stack === undefined || stage === undefined || id === undefined
+      ? undefined
+      : ({ stack, stage, id } satisfies RuntimeOwner);
+  });
+});

package/src/Sandbox.ts

@@ -0,0 +1,402 @@
+import * as BuildPlan from "@alchemy.run/docker/BuildPlan";
+import * as image from "@distilled.cloud/modal/image";
+import * as secret from "@distilled.cloud/modal/secret";
+import type * as Bundle from "alchemy/Bundle/Bundle";
+import { deepEqual, isResolved } from "alchemy/Diff";
+import { mountInstallLines } from "alchemy/Mount";
+import { Platform, type Main, type PlatformProps } from "alchemy/Platform";
+import * as Provider from "alchemy/Provider";
+import type { Resource } from "alchemy/Resource";
+import {
+  createHostRuntimeContext,
+  type HostRuntimeContext,
+  type ServerHost,
+} from "alchemy/Runtime/Process";
+import { Stack } from "alchemy/Stack";
+import { sha256Object } from "alchemy/Util/sha256";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import type { App } from "./App.ts";
+import { buildImage, ImageBuildOps } from "./ImageBuild.ts";
+import { checkCommands, lowerPlan, MODAL_CAPABILITIES } from "./ImagePlan.ts";
+import { envNameOf, objectName } from "./internal.ts";
+import { resolveDeclarations } from "./internal/Declared.ts";
+import {
+  boundCapabilities,
+  boundMounts,
+  checkModalMounts,
+  type ModalMounts,
+  type Mount,
+  type MountBindings,
+  type MountContract,
+  modalMountsOf,
+} from "./Mounts.ts";
+import type { Providers } from "./Providers.ts";
+import { putSecret } from "./Secret.ts";
+
+const DEFAULT_PORT = 8080;
+
+type Ref<T> = T | Effect.Effect<T, never, Providers>;
+
+export interface SandboxProps extends PlatformProps {
+  /**
+   * Module entrypoint, bundled and baked into the sandbox image. Typically
+   * `import.meta.url`. A change to the bundle builds a new image.
+   */
+  main: string;
+  /** The App sandboxes run in. */
+  app: Ref<App>;
+  /**
+   * Base image the bundle runs on. It needs Bun on the `PATH`.
+   * @default "oven/bun:1"
+   */
+  image?: string;
+  /** Dockerfile lines run on the base before the bundle is added. */
+  commands?: string[];
+  /**
+   * Port the program's `fetch` handler listens on, opened as an encrypted
+   * tunnel on every sandbox.
+   * @default 8080
+   */
+  port?: number;
+  /**
+   * Named export to load from `main`.
+   * @default "default"
+   */
+  handler?: string;
+  /**
+   * Extra environment variables for the program. Stored, with the
+   * bindings' env, in a Modal Secret attached to every sandbox.
+   */
+  env?: Record<string, any>;
+  /** Bundler options. */
+  build?: Bundle.BundleConfig;
+  /**
+   * Volumes and cloud buckets mounted into every sandbox:
+   * `[{ volume: Data, path: "/data" }]`. `Modal.MountVolume` and
+   * `Modal.MountBucket` in the program add more.
+   */
+  mounts?: Mount[];
+}
+
+export interface SandboxAttributes {
+  /** The image with the bundled program (`im-…`). */
+  imageId: string;
+  /** The App sandboxes run in. */
+  appId: string;
+  /** Name of the App. */
+  appName: string | undefined;
+  /** Environment of the App. */
+  environment: string | undefined;
+  /** The Modal Secret holding the program's env (bindings' credentials included). */
+  secretId: string;
+  /** Name of that secret. */
+  secretName: string;
+  /** Port the program listens on. */
+  port: number;
+  /** The command each sandbox runs. */
+  command: string[];
+  /** Modal's volume and bucket mounts every sandbox gets (props and bindings). */
+  mounts: ModalMounts;
+  /** Content hash of the bundle and image inputs. */
+  hash: string;
+}
+
+export type Sandbox = Resource<
+  "Modal.Sandbox",
+  SandboxProps,
+  SandboxAttributes,
+  { env?: Record<string, any>; mounts?: MountContract },
+  Providers
+>;
+
+export type SandboxServices = ServerHost;
+export type SandboxShape = Main<SandboxServices>;
+export type SandboxRuntimeContext = HostRuntimeContext;
+
+/**
+ * An Effect program that runs in Modal sandboxes. Alchemy bundles `main`,
+ * builds it into an image on Modal's builder (no Docker), and stores its
+ * env, including the credentials its bindings need, in a Modal Secret.
+ * `Modal.CreateSandbox(Agent)` then boots sandboxes that run the program and
+ * serve its `fetch` handler; `sandbox.getTcpPort()` reaches it.
+ *
+ * Each sandbox is an isolated instance: give one to every user, session or
+ * task, and terminate it when the work is done. A sandbox lives at most 24
+ * hours. Bindings work inside it like on any host, so the program can read a
+ * Modal Volume or a Cloudflare R2 bucket.
+ *
+ * ### Effect program
+ * **Example:** An agent that answers over HTTP
+ * ```typescript
+ * // src/Agent.ts
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Coder } from "./Coder.ts";
+ *
+ * export default class Agent extends Modal.Sandbox<Agent>()(
+ *   "Agent",
+ *   { main: import.meta.url, app: Coder },
+ *   Effect.gen(function* () {
+ *     return {
+ *       fetch: Effect.succeed(HttpServerResponse.text("ready")),
+ *     };
+ *   }),
+ * ) {}
+ * ```
+ *
+ * ### Async program
+ * **Example:** A plain HTTP server, no Effect (it runs on Bun)
+ * ```typescript
+ * // src/Agent.ts
+ * import * as Modal from "@alchemy.run/modal";
+ * import { Coder } from "./Coder.ts";
+ *
+ * export const Agent = Modal.Sandbox("Agent", {
+ *   main: "./src/agent-server.ts",
+ *   app: Coder,
+ *   env: { GREETING: "hello" },
+ * });
+ * export type AgentEnv = Modal.InferEnv<typeof Agent>;
+ * ```
+ *
+ * ```typescript
+ * // src/agent-server.ts
+ * import { createServer } from "node:http";
+ * import type { AgentEnv } from "./Agent.ts";
+ *
+ * const env = process.env as unknown as AgentEnv;
+ *
+ * createServer((_request, response) => response.end(env.GREETING)).listen(Number(process.env.PORT));
+ * ```
+ *
+ * ### Starting instances
+ * **Example:** One sandbox per request from a Worker
+ * ```typescript
+ * // src/Api.ts
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as HttpClientRequest from "effect/http/HttpClientRequest";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import Agent from "./Agent.ts";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url, compatibility: { flags: ["nodejs_compat"] } },
+ *   Effect.gen(function* () {
+ *     const agents = yield* Modal.CreateSandbox(Agent);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const agent = yield* agents.create({ timeout: "10 minutes" });
+ *         const port = yield* agent.getTcpPort();
+ *         const response = yield* port.fetch(HttpClientRequest.get("/"));
+ *         const text = yield* response.text;
+ *         yield* agent.terminate();
+ *         return HttpServerResponse.text(text);
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Modal.CreateSandboxHttp)),
+ * ) {}
+ * ```
+ *
+ * ### Bindings inside the sandbox
+ * **Example:** Read a Modal Volume from the program
+ * ```typescript
+ * // src/Agent.ts
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Coder, Models } from "./Coder.ts";
+ *
+ * export default class Agent extends Modal.Sandbox<Agent>()(
+ *   "Agent",
+ *   { main: import.meta.url, app: Coder },
+ *   Effect.gen(function* () {
+ *     const models = yield* Modal.ReadVolume(Models);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const files = yield* models.listFiles("/");
+ *         return yield* HttpServerResponse.json(files);
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Modal.ReadVolumeHttp)),
+ * ) {}
+ * ```
+ *
+ * ### Configuration
+ * **Example:** A GPU-ready base and a custom port
+ * ```typescript
+ * export default class Trainer extends Modal.Sandbox<Trainer>()(
+ *   "Trainer",
+ *   {
+ *     main: import.meta.url,
+ *     app: Coder,
+ *     image: "nvidia/cuda:12.4.1-runtime-ubuntu22.04",
+ *     commands: ["RUN apt-get update && apt-get install -y curl unzip && curl -fsSL https://bun.sh/install | bash && ln -s /root/.bun/bin/bun /usr/local/bin/bun"],
+ *     port: 3000,
+ *   },
+ *   program,
+ * ) {}
+ * ```
+ *
+ * @resource
+ * @product Sandbox
+ */
+export const Sandbox: Platform<Sandbox, SandboxServices, SandboxShape, SandboxRuntimeContext> =
+  Platform("Modal.Sandbox", {
+    createRuntimeContext: createHostRuntimeContext("Modal.Sandbox"),
+    // `{ app: Coder }` at module scope is an Effect: yield it so the App is
+    // registered and `news.app` is resolved attributes at reconcile.
+    transformProps: (_id, props) =>
+      Effect.gen(function* () {
+        if (globalThis.__ALCHEMY_RUNTIME__) return props;
+        const app = Effect.isEffect(props.app)
+          ? yield* props.app as Effect.Effect<App, never, Providers>
+          : props.app;
+        const mounts =
+          props.mounts === undefined
+            ? undefined
+            : ((yield* resolveDeclarations(props.mounts)) as Mount[]);
+        return { ...props, app, mounts };
+      }),
+  });
+
+const bootstrapEntry =
+  (handler: string) =>
+  (importPath: string): string =>
+    `
+import { bootstrap } from "@alchemy.run/modal/Bootstrap";
+import { ${handler} as entrypoint } from ${JSON.stringify(importPath)};
+
+await bootstrap(entrypoint);
+`;
+
+const appOf = (value: unknown) => {
+  const rec = (value ?? {}) as { appId?: string; name?: string; environment?: unknown };
+  return { appId: rec.appId ?? "", appName: rec.name, environment: envNameOf(rec.environment) };
+};
+
+/** An env value as a string, as the program's `process.env` sees it. */
+const envText = (value: unknown): string =>
+  typeof value === "string"
+    ? value
+    : Redacted.isRedacted(value)
+      ? String(Redacted.value(value))
+      : JSON.stringify(value ?? null);
+
+export const SandboxProvider = () =>
+  Provider.effect(
+    Sandbox,
+    Effect.gen(function* () {
+      const stack = yield* Stack;
+
+      /** Plan the program's image (bundle + bootstrap) with the shared BuildPlan. */
+      const prepare = Effect.fn(function* (
+        news: SandboxProps,
+        port: number,
+        bindings: MountBindings,
+      ) {
+        // Other providers' mount clients go into the image; Modal can't
+        // provide FUSE or NFS, so those that need it fail here.
+        const capabilities = boundCapabilities(bindings);
+        yield* checkModalMounts("Modal.Sandbox", capabilities);
+        const plan = yield* BuildPlan.plan(
+          {
+            main: news.main,
+            image: news.image,
+            handler: news.handler,
+            build: news.build,
+          },
+          {
+            capabilities: { ...MODAL_CAPABILITIES, target: "Modal.Sandbox" },
+            port,
+            bootstrap: news.isExternal ? undefined : bootstrapEntry(news.handler ?? "default"),
+            install: mountInstallLines(capabilities),
+          },
+        );
+        const extra = yield* checkCommands(news.commands ?? []);
+        const spec = yield* lowerPlan(plan, extra);
+        const hash = yield* sha256Object({ plan: plan.hash, extra });
+        const command = BuildPlan.startCommand(plan) ?? [];
+        return { spec, hash, command: [...command] };
+      });
+
+      return {
+        stables: ["appId", "secretName"],
+        diff: Effect.fn(function* ({ news, output, newBindings }) {
+          if (!isResolved(news) || !isResolved(newBindings) || output === undefined) {
+            return undefined;
+          }
+          if (appOf(news.app).appId !== output.appId) return { action: "replace" } as const;
+          const { hash } = yield* prepare(news, news.port ?? DEFAULT_PORT, newBindings);
+          if (hash !== output.hash) return { action: "update" } as const;
+          const mounts = yield* modalMountsOf([
+            ...(news.mounts ?? []),
+            ...boundMounts(newBindings),
+          ]);
+          return deepEqual(mounts, output.mounts) ? undefined : ({ action: "update" } as const);
+        }),
+        read: Effect.fn(function* ({ output }) {
+          if (output === undefined) return undefined;
+          const found = yield* image
+            .imageFromId({ imageId: output.imageId })
+            .pipe(Effect.catchTag("ImageNotFound", () => Effect.undefined));
+          return found?.imageId ? output : undefined;
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output, session, bindings }) {
+          const app = appOf(news.app);
+          // The props' mounts, then the ones `Modal.MountVolume` / `MountBucket` bound.
+          const mounts = yield* modalMountsOf([...(news.mounts ?? []), ...boundMounts(bindings)]);
+          const port = news.port ?? DEFAULT_PORT;
+          const secretName = output?.secretName ?? `${yield* objectName(id, undefined, 58)}-env`;
+
+          // Sync the program's env (bindings' credentials included) into a
+          // secret every sandbox attaches; values never enter the image.
+          const env: Record<string, string> = {
+            ALCHEMY_STACK_NAME: stack.name,
+            ALCHEMY_STAGE: stack.stage,
+            ALCHEMY_PHASE: "runtime",
+            HOST: "0.0.0.0",
+            PORT: String(port),
+          };
+          for (const [key, value] of Object.entries(news.env ?? {})) env[key] = envText(value);
+          const stored = yield* putSecret(
+            yield* secret.secretGetOrCreate,
+            secretName,
+            app.environment,
+            env,
+          );
+
+          // Ensure the image: Modal reuses a cached build for the same inputs.
+          const { spec, hash, command } = yield* prepare(news, port, bindings);
+          const imageId =
+            output !== undefined && output.hash === hash && output.appId === app.appId
+              ? output.imageId
+              : yield* buildImage(yield* ImageBuildOps, app.appId, spec, { note: session.note });
+
+          return {
+            imageId,
+            appId: app.appId,
+            appName: app.appName,
+            environment: app.environment,
+            secretId: stored.secretId,
+            secretName,
+            port,
+            command,
+            mounts,
+            hash,
+          };
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* secret
+            .deleteSecret({ secretId: output.secretId })
+            .pipe(Effect.catchTag("SecretNotFound", () => Effect.void));
+          yield* image
+            .deleteImage({ imageId: output.imageId })
+            .pipe(Effect.catchTag("ImageNotFound", () => Effect.void));
+        }),
+      };
+    }),
+  );