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

package/src/internal/Runtime.ts

@@ -0,0 +1,386 @@
+import * as classes from "@distilled.cloud/modal/classes";
+import * as functions from "@distilled.cloud/modal/functions";
+import * as secret from "@distilled.cloud/modal/secret";
+import { isResolved } from "alchemy/Diff";
+import type { Input } from "alchemy/Input";
+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 { ContainerProps, Ref } from "../Container.ts";
+import { gpuConfig } from "../ImageBuild.ts";
+import { envNameOf, objectName, seconds } from "../internal.ts";
+import {
+  boundCapabilities,
+  boundMounts,
+  type ModalMounts,
+  type Mount,
+  type MountBindings,
+  modalMountsOf,
+} from "../Mounts.ts";
+import type { Providers } from "../Providers.ts";
+import { putSecret } from "../Secret.ts";
+import { resolveDeclarations } from "./Declared.ts";
+import {
+  buildRuntimeImage,
+  classTag,
+  clientMount,
+  DEFAULT_PORT,
+  entrypointMount,
+  ModalDeployUnexpectedResponse,
+  planRuntimeImage,
+  publishFunction,
+} from "./Deploy.ts";
+import { ENTRYPOINT_MODULE } from "./Entrypoint.ts";
+import { RPC_CALLERS_ENV, type RpcCallerBinding, rpcCallersOf } from "./RpcAuth.ts";
+
+/** What a runtime's bindings attach: mounts, and the keys of RPC callers. */
+type RuntimeBindings = ReadonlyArray<{
+  readonly data: { readonly mounts?: MountBindings[number]["data"]["mounts"] } & RpcCallerBinding;
+}>;
+
+/** Attributes shared by `Modal.Function` and `Modal.Server`. */
+export interface RuntimeAttributes {
+  /** Function ID (`fu-…`). */
+  functionId: string;
+  /** Name of the function in its App. */
+  name: string;
+  /** The App the function is deployed in. */
+  appId: string;
+  /** Name of that App. */
+  appName: string | undefined;
+  /** Environment of that App. */
+  environment: string | undefined;
+  /** The image with the bundled program (`im-…`). */
+  imageId: string;
+  /** 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 the entrypoint starts. */
+  command: string[];
+  /** Content hash of the bundle, image and function definition. */
+  hash: string;
+  /** The class (`cs-…`) of a function with RPC methods, which Modal runs as a class. */
+  classId?: string | undefined;
+}
+
+/** What differs between a Function and a Server. */
+export interface RuntimeKind<P extends ContainerProps> {
+  /** Resource type, e.g. `Modal.Function`. */
+  readonly type: string;
+  /** The Function fields specific to the kind (webhook, schedule, HTTP config, ...). */
+  readonly definition: (
+    props: P,
+    context: { readonly port: number; readonly startupTimeout: number },
+  ) => functions.Function;
+  /** The program's bootstrap for an Effect-native `main`. */
+  readonly bootstrap: (handler: string) => (importPath: string) => string;
+  /** Env the kind adds to the program's (e.g. turning RPC on). */
+  readonly env?: (props: P) => Record<string, string>;
+}
+
+const resolveRef = <T>(value: Ref<T>) =>
+  Effect.isEffect(value) ? (value as Effect.Effect<T, never, Providers>) : Effect.succeed(value);
+
+/**
+ * `{ app: Coder, mounts: [{ volume: Data, path: "/data" }] }` at module scope
+ * holds Effects: yield them so the resources are registered and the props
+ * hold their resolved attributes at reconcile.
+ */
+export const resolveContainerProps = <P extends ContainerProps>(_id: string, props: P) =>
+  Effect.gen(function* () {
+    if (globalThis.__ALCHEMY_RUNTIME__) return props;
+    const app = yield* resolveRef(props.app);
+    const proxy = props.proxy === undefined ? undefined : yield* resolveRef(props.proxy);
+    const secrets =
+      props.secrets === undefined ? undefined : yield* Effect.forEach(props.secrets, resolveRef);
+    const mounts =
+      props.mounts === undefined
+        ? undefined
+        : ((yield* resolveDeclarations(props.mounts)) as Mount[]);
+    return { ...props, app, proxy, secrets, mounts };
+  });
+
+/** The resolved app of the props. */
+export 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) };
+};
+
+const idOf = (value: unknown, key: string): string | undefined =>
+  typeof value === "object" && value !== null && key in value
+    ? ((value as Record<string, unknown>)[key] as string | undefined)
+    : undefined;
+
+/** 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);
+
+/** The function definition fields every kind shares. */
+const baseDefinition = (
+  props: ContainerProps,
+  context: {
+    readonly tag: string;
+    readonly appName: string | undefined;
+    readonly timeout: number;
+    readonly startupTimeout: number;
+  },
+  mounts: ModalMounts,
+): functions.Function => ({
+  moduleName: ENTRYPOINT_MODULE,
+  functionName: context.tag,
+  definitionType: "DEFINITION_TYPE_FILE",
+  functionType: "FUNCTION_TYPE_FUNCTION",
+  resources: {
+    milliCpu: props.cpu !== undefined ? Math.round(props.cpu * 1000) : undefined,
+    milliCpuMax: props.cpuLimit !== undefined ? Math.round(props.cpuLimit * 1000) : undefined,
+    memoryMb: props.memory,
+    memoryMbMax: props.memoryLimit,
+    gpuConfig: gpuConfig(props.gpu),
+    ephemeralDiskMb: props.ephemeralDisk,
+  },
+  volumeMounts: mounts.volumeMounts,
+  cloudBucketMounts: mounts.cloudBucketMounts,
+  proxyId: idOf(props.proxy, "proxyId"),
+  timeoutSecs: Math.round(context.timeout),
+  startupTimeoutSecs: Math.round(context.startupTimeout),
+  cloudProviderStr: props.cloud ?? "",
+  appName: context.appName ?? "",
+  schedulerPlacement:
+    props.regions !== undefined || props.nonpreemptible
+      ? { regions: props.regions, nonpreemptible: props.nonpreemptible }
+      : undefined,
+  autoscalerSettings: {
+    minContainers: props.minContainers,
+    maxContainers: props.maxContainers,
+    bufferContainers: props.bufferContainers,
+    scaleupWindow: props.scaleupWindow,
+    scaledownWindow: props.scaledownWindow,
+  },
+  // Older mirrors of `autoscalerSettings` the Python client still sets.
+  warmPoolSize: props.minContainers ?? 0,
+  concurrencyLimit: props.maxContainers ?? 0,
+  ExperimentalBufferContainers: props.bufferContainers ?? 0,
+  taskIdleTimeoutSecs: props.scaledownWindow ?? 0,
+  checkpointingEnabled: props.enableMemorySnapshot,
+  blockNetwork: props.blockNetwork,
+  untrusted: props.restrictModalAccess,
+  i6pnEnabled: props.i6pn,
+  methodDefinitionsSet: true,
+  mountClientDependencies: true,
+  ExperimentalConcurrentCancellations: true,
+});
+
+/**
+ * The lifecycle shared by every Modal runtime: a function in an App whose
+ * container runs the bundled program behind Alchemy's Python entrypoint.
+ *
+ * 1. the program's env goes into a Modal Secret (values never enter the image);
+ * 2. the image is the base plus standalone Python plus the bundle, built by
+ *    Modal and reused while its inputs don't change;
+ * 3. `FunctionCreate` writes the definition (with the entrypoint and client
+ *    mounts), updating the existing function in place;
+ * 4. the App is republished with the function, keeping its other functions.
+ */
+export const runtimeLifecycle = <P extends ContainerProps>(kind: RuntimeKind<P>) =>
+  Effect.gen(function* () {
+    const stack = yield* Stack;
+
+    const prepare = Effect.fn(function* (id: string, news: P, bindings: RuntimeBindings) {
+      const port = news.port ?? DEFAULT_PORT;
+      const tag = news.name ?? id;
+      const app = appOf(news.app);
+      const timeout = seconds(news.timeout) ?? 300;
+      const startupTimeout = seconds(news.startupTimeout) ?? timeout;
+      const image = yield* planRuntimeImage(
+        kind.type,
+        news,
+        port,
+        news.isExternal ? undefined : kind.bootstrap(news.handler ?? "default"),
+        boundCapabilities(bindings),
+      );
+      // The props' mounts, then the ones `Modal.MountVolume` / `MountBucket` bound.
+      const mounts = yield* modalMountsOf([...(news.mounts ?? []), ...boundMounts(bindings)]);
+      const base = baseDefinition(
+        news,
+        { tag, appName: app.appName, timeout, startupTimeout },
+        mounts,
+      );
+      const specific = kind.definition(news, { port, startupTimeout });
+      const definition: functions.Function = {
+        ...base,
+        ...specific,
+        // A class's service function is named `<tag>.*`, as Modal's clients name it.
+        functionName: specific.isClass ? classTag(tag) : tag,
+        autoscalerSettings: { ...base.autoscalerSettings, ...specific.autoscalerSettings },
+      };
+      const secretIds = (news.secrets ?? []).flatMap((s) => idOf(s, "secretId") ?? []);
+      const env = {
+        ...Object.fromEntries(
+          Object.entries(news.env ?? {}).map(([key, value]) => [key, envText(value)]),
+        ),
+        ...kind.env?.(news),
+        // The callers whose keys open the program's RPC methods.
+        ...(rpcCallersOf(bindings).length > 0
+          ? { [RPC_CALLERS_ENV]: JSON.stringify(rpcCallersOf(bindings)) }
+          : {}),
+      };
+      const hash = yield* sha256Object({ image: image.hash, definition, secretIds, env });
+      return { port, tag, app, image, definition, secretIds, env, hash };
+    });
+
+    return {
+      stables: ["appId", "name", "secretName"] as Array<keyof RuntimeAttributes>,
+      diff: Effect.fn(function* ({
+        id,
+        news,
+        output,
+        newBindings,
+      }: {
+        id: string;
+        news: Input<P>;
+        output: RuntimeAttributes | undefined;
+        newBindings: Input<RuntimeBindings>;
+      }) {
+        if (!isResolved(news) || !isResolved(newBindings) || output === undefined) {
+          return undefined;
+        }
+        if (appOf(news.app).appId !== output.appId) return { action: "replace" } as const;
+        if ((news.name ?? id) !== output.name) return { action: "replace" } as const;
+        const { hash } = yield* prepare(id, news, newBindings);
+        return hash !== output.hash ? ({ action: "update" } as const) : undefined;
+      }),
+      read: Effect.fn(function* ({ output }: { output: RuntimeAttributes | undefined }) {
+        if (output === undefined) return undefined;
+        const found = yield* functions
+          .functionGetById({ functionId: output.functionId })
+          .pipe(Effect.catchTag("FunctionNotFound", () => Effect.undefined));
+        return found?.function ? output : undefined;
+      }),
+      reconcile: Effect.fn(function* ({
+        id,
+        news,
+        output,
+        session,
+        bindings,
+      }: {
+        id: string;
+        news: P;
+        output: RuntimeAttributes | undefined;
+        session: { note: (message: string) => Effect.Effect<void> };
+        bindings: RuntimeBindings;
+      }) {
+        const {
+          port,
+          tag,
+          app,
+          image,
+          definition,
+          secretIds,
+          env: programEnv,
+          hash,
+        } = yield* prepare(id, news, bindings);
+        for (const warning of image.warnings) yield* session.note(warning);
+        const secretName = output?.secretName ?? `${yield* objectName(id, undefined, 58)}-env`;
+
+        // Sync the program's env (bindings' credentials included) into the
+        // secret the function attaches; values never enter the image.
+        const env: Record<string, string> = {
+          ALCHEMY_STACK_NAME: stack.name,
+          ALCHEMY_STAGE: stack.stage,
+          ALCHEMY_PHASE: "runtime",
+          ALCHEMY_COMMAND: JSON.stringify(image.command),
+          HOST: "0.0.0.0",
+          PORT: String(port),
+        };
+        Object.assign(env, programEnv);
+        const stored = yield* putSecret(
+          yield* secret.secretGetOrCreate,
+          secretName,
+          app.environment,
+          env,
+        );
+
+        // Ensure the image: Modal reuses a cached build for the same inputs.
+        const imageId =
+          output !== undefined && output.hash === hash && output.appId === app.appId
+            ? output.imageId
+            : yield* buildRuntimeImage(app.appId, image, {
+                builderVersion: news.builderVersion,
+                gpu: news.gpu,
+                note: session.note,
+              });
+
+        const mountIds = [yield* clientMount, yield* entrypointMount(app.appId)];
+        yield* session.note(`Deploying ${kind.type} ${tag}...`);
+        const created = yield* functions.createFunction({
+          appId: app.appId,
+          function: {
+            ...definition,
+            imageId,
+            mountIds,
+            secretIds: [stored.secretId, ...secretIds],
+          },
+          existingFunctionId: output?.appId === app.appId ? output.functionId : undefined,
+        });
+        if (!created.functionId) {
+          return yield* new ModalDeployUnexpectedResponse({
+            message: `Modal returned no id for function ${tag}`,
+          });
+        }
+        for (const warning of created.serverWarnings ?? []) {
+          if (warning.message) yield* session.note(warning.message);
+        }
+        // A class function needs its class: its containers hydrate it from
+        // the App layout, under the function's name.
+        const classId = definition.isClass
+          ? (yield* classes.createClass({
+              appId: app.appId,
+              existingClassId: output?.appId === app.appId ? output.classId : undefined,
+              onlyClassFunction: true,
+            })).classId
+          : undefined;
+        yield* publishFunction(app, tag, {
+          functionId: created.functionId,
+          definitionId: created.handleMetadata?.definitionId,
+          classId,
+        });
+        return {
+          attributes: {
+            functionId: created.functionId,
+            name: tag,
+            appId: app.appId,
+            appName: app.appName,
+            environment: app.environment,
+            imageId,
+            secretId: stored.secretId,
+            secretName,
+            port,
+            command: image.command,
+            hash,
+            classId,
+          } satisfies RuntimeAttributes,
+          metadata: created.handleMetadata,
+        };
+      }),
+      delete: Effect.fn(function* ({ output }: { output: RuntimeAttributes }) {
+        // Republish the App without the function; stopping the App (its own
+        // resource) is what removes everything else.
+        yield* publishFunction(output, output.name, undefined).pipe(
+          Effect.catchTag("AppNotFound", () => Effect.void),
+        );
+        yield* secret
+          .deleteSecret({ secretId: output.secretId })
+          .pipe(Effect.catchTag("SecretNotFound", () => Effect.void));
+        // The image stays: Modal content-addresses builds, so another
+        // function or sandbox may boot from the same image id.
+      }),
+    };
+  });

package/src/internal/Tags.ts

@@ -0,0 +1,44 @@
+import { createInternalTags, hasTags, type Tags } from "alchemy/Tags";
+import * as Effect from "effect/Effect";
+
+/**
+ * Modal tag keys and values must match `^[a-zA-Z0-9._-]{1,63}$`, so
+ * Alchemy's `alchemy::stack` / `alchemy::stage` / `alchemy::id` ownership
+ * tags are stored as `alchemy.stack` / `alchemy.stage` / `alchemy.id`, and
+ * their values are rewritten into that character set (`/` in a nested
+ * logical ID becomes `__`).
+ */
+export const ALCHEMY_TAG_PREFIX = "alchemy.";
+
+const INTERNAL_PREFIX = "alchemy::";
+
+const toModalKey = (key: string): string =>
+  key.startsWith(INTERNAL_PREFIX)
+    ? `${ALCHEMY_TAG_PREFIX}${key.slice(INTERNAL_PREFIX.length)}`
+    : key;
+
+const toModalValue = (value: string): string => {
+  const cleaned = value
+    .replaceAll("/", "__")
+    .replace(/[^A-Za-z0-9._-]/g, "-")
+    .slice(0, 63);
+  return cleaned.length > 0 ? cleaned : "-";
+};
+
+/** Alchemy's ownership tags in Modal's tag format. */
+export const createModalInternalTags = Effect.fn(function* (id: string) {
+  const tags = yield* createInternalTags(id);
+  return Object.fromEntries(
+    Object.entries(tags).map(([key, value]) => [toModalKey(key), toModalValue(value)]),
+  );
+});
+
+/** Whether observed Modal tags carry this resource's ownership tags. */
+export const hasModalAlchemyTags = Effect.fn(function* (id: string, tags: Tags | undefined) {
+  return hasTags(yield* createModalInternalTags(id), tags);
+});
+
+/** Whether observed Modal tags carry any Alchemy ownership tag. */
+export const isAlchemyTagged = (
+  tags: Readonly<Record<string, string | undefined>> | undefined,
+): boolean => Object.keys(tags ?? {}).some((key) => key.startsWith(ALCHEMY_TAG_PREFIX));

package/src/internal/TcpConnect.ts

@@ -0,0 +1,78 @@
+import * as Effect from "effect/Effect";
+import * as Socket from "effect/socket/Socket";
+import { isWorkerd } from "./Transport.ts";
+
+/** The part of `cloudflare:sockets` this module uses. */
+type CloudflareConnect = (
+  address: { hostname: string; port: number },
+  options: { secureTransport: "on" | "off"; allowHalfOpen: boolean },
+) => {
+  readonly readable: ReadableStream<Uint8Array>;
+  readonly writable: WritableStream<Uint8Array>;
+  close(): Promise<void>;
+};
+
+/** The parts of `node:net`, `node:tls` and `node:stream` this module uses. */
+interface NodeDuplex {
+  destroy(): void;
+}
+type NodeConnect = (options: { host: string; port: number; servername?: string }) => NodeDuplex;
+interface NodeStreamModule {
+  readonly Duplex: {
+    toWeb(duplex: NodeDuplex): Socket.InputTransformStream;
+  };
+}
+
+// Non-literal specifiers keep a bundler from pulling one runtime's sockets
+// into the other's bundle: workerd resolves `cloudflare:sockets` at runtime,
+// and Node resolves its built-ins.
+const CLOUDFLARE_SOCKETS = "cloudflare:sockets";
+const NODE_NET = "node:net";
+const NODE_TLS = "node:tls";
+const NODE_STREAM = "node:stream";
+
+const importModule = <A>(specifier: string) =>
+  Effect.tryPromise({
+    try: () => import(/* @vite-ignore */ specifier) as Promise<A>,
+    catch: (cause) =>
+      Socket.SocketError.make({ reason: Socket.SocketOpenError.make({ kind: "Unknown", cause }) }),
+  });
+
+const openCloudflare = (host: string, port: number, tls: boolean) =>
+  Effect.acquireRelease(
+    Effect.map(importModule<{ connect: CloudflareConnect }>(CLOUDFLARE_SOCKETS), ({ connect }) =>
+      connect(
+        { hostname: host, port },
+        { secureTransport: tls ? "on" : "off", allowHalfOpen: false },
+      ),
+    ),
+    (socket) => Effect.promise(() => socket.close().catch(() => undefined)),
+  );
+
+const openNode = (host: string, port: number, tls: boolean) =>
+  Effect.acquireRelease(
+    Effect.gen(function* () {
+      const { Duplex } = yield* importModule<NodeStreamModule>(NODE_STREAM);
+      const { connect } = yield* importModule<{ connect: NodeConnect }>(tls ? NODE_TLS : NODE_NET);
+      const duplex = connect(tls ? { host, port, servername: host } : { host, port });
+      return { duplex, stream: Duplex.toWeb(duplex) };
+    }),
+    ({ duplex }) => Effect.sync(() => duplex.destroy()),
+  ).pipe(Effect.map(({ stream }) => stream));
+
+/**
+ * A TCP socket to `host:port`, over TLS when `tls` is set: `cloudflare:sockets`
+ * on workerd, Node's `net`/`tls` elsewhere. It connects when run.
+ */
+export const connectTcp = (options: {
+  readonly host: string;
+  readonly port: number;
+  readonly tls: boolean;
+}): Effect.Effect<Socket.Socket> =>
+  Socket.fromTransformStream(
+    Effect.suspend(() =>
+      isWorkerd()
+        ? openCloudflare(options.host, options.port, options.tls)
+        : openNode(options.host, options.port, options.tls),
+    ),
+  );

package/src/internal/Transport.ts

@@ -0,0 +1,25 @@
+import { GrpcTransport } from "@distilled.cloud/core/grpc-transport";
+import * as CloudflareSockets from "@distilled.cloud/core/grpc-transport-cloudflare-sockets";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import type * as HttpClient from "effect/http/HttpClient";
+import * as Layer from "effect/Layer";
+
+/** Whether this code runs on workerd (a Cloudflare Worker or Durable Object). */
+export const isWorkerd = (): boolean =>
+  typeof navigator !== "undefined" && navigator.userAgent === "Cloudflare-Workers";
+
+/**
+ * How Modal calls leave this runtime: `fetch`, and on a Cloudflare Worker,
+ * distilled's `cloudflare:sockets` gRPC transport. `api.modal.com` is behind
+ * Cloudflare, and a Worker's `fetch` to it takes Cloudflare's internal
+ * Worker-to-site path, which resets Modal's gRPC upstream (`grpc-status: 14`).
+ * Other HTTP calls (blob uploads, the user's own endpoints) keep `fetch`.
+ */
+export const ModalTransport: Layer.Layer<HttpClient.HttpClient> = Layer.mergeAll(
+  FetchHttpClient.layer,
+  Layer.effect(
+    GrpcTransport,
+    Effect.sync(() => (isWorkerd() ? CloudflareSockets.client : undefined)),
+  ),
+);

package/src/internal.ts

@@ -0,0 +1,147 @@
+import type { Credentials } from "@distilled.cloud/modal/Credentials";
+import * as environment from "@distilled.cloud/modal/environment";
+import type { ListPagination } from "@distilled.cloud/modal/volume";
+import { createPhysicalName } from "alchemy/PhysicalName";
+import * as Effect from "effect/Effect";
+import type * as HttpClient from "effect/http/HttpClient";
+
+/**
+ * Modal object names: letters, digits, `-`, `.` and `_`, shorter than 64
+ * characters. Names are unique per environment and kind.
+ */
+export const objectName = (id: string, name: string | undefined, maxLength = 63) =>
+  name !== undefined ? Effect.succeed(name) : createPhysicalName({ id, maxLength, delimiter: "-" });
+
+/**
+ * The environment a Modal call targets. Modal resolves an empty name to the
+ * workspace's default environment, so `undefined` stays `""` on the wire and
+ * `undefined` in attributes.
+ */
+export const environmentOf = (name: string | undefined): string => name ?? "";
+
+/** Seconds of a duration given as seconds or a `"10 minutes"`-style string. */
+export const seconds = (value: number | string | undefined): number | undefined => {
+  if (value === undefined) return undefined;
+  if (typeof value === "number") return value;
+  const match =
+    /^\s*(\d+(?:\.\d+)?)\s*(ms|millis|milliseconds?|s|secs?|seconds?|m|mins?|minutes?|h|hours?)\s*$/i.exec(
+      value,
+    );
+  if (!match) return Number(value);
+  const n = Number(match[1]);
+  const unit = match[2]!.toLowerCase();
+  if (unit.startsWith("ms") || unit.startsWith("milli")) return n / 1000;
+  if (unit.startsWith("h")) return n * 3600;
+  if (unit.startsWith("m")) return n * 60;
+  return n;
+};
+
+/**
+ * Every item of a Modal `List*` call. Modal pages by creation time: each
+ * request takes `maxObjects` and `createdBefore`, the creation time of the
+ * oldest item seen so far.
+ */
+export const listAll: <T, E, R>(
+  fetch: (pagination: ListPagination) => Effect.Effect<ReadonlyArray<T>, E, R>,
+  createdAt: (item: T) => number | undefined,
+  pageSize?: number,
+) => Effect.Effect<T[], E, R> = Effect.fn(function* <T, E, R>(
+  fetch: (pagination: ListPagination) => Effect.Effect<ReadonlyArray<T>, E, R>,
+  createdAt: (item: T) => number | undefined,
+  pageSize = 100,
+) {
+  const all: T[] = [];
+  let before: number | undefined;
+  for (let page = 0; page < 1_000; page++) {
+    const items = yield* fetch({ maxObjects: pageSize, createdBefore: before });
+    all.push(...items);
+    if (items.length < pageSize) break;
+    const oldest = Math.min(...items.map((item) => createdAt(item) ?? Number.POSITIVE_INFINITY));
+    if (!Number.isFinite(oldest) || oldest === before) break;
+    before = oldest;
+  }
+  return all;
+});
+
+/**
+ * The names of every environment in the workspace, for `list` operations that
+ * enumerate objects across environments.
+ */
+export const environmentNames = Effect.gen(function* () {
+  const response = yield* environment.listEnvironment({});
+  return (response.items ?? []).flatMap((item) => (item.name ? [item.name] : []));
+});
+
+/** A wire `map<string, string>` without the absent entries proto3 JSON allows. */
+export const stringMap = (
+  map: Readonly<Record<string, string | undefined>> | undefined,
+): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(map ?? {}).flatMap(([key, value]) =>
+      value === undefined ? [] : [[key, value]],
+    ),
+  );
+
+/**
+ * Whether a name was generated by `createPhysicalName` (it ends in a
+ * 16-character base32 instance suffix, or an 8-character truncation hash plus
+ * the suffix). Modal objects other than Apps and Sandboxes have no tags, so
+ * `list` (and `alchemy nuke`) only enumerate objects with generated names
+ * and the objects runtimes created (`isRuntimeName`); objects given an
+ * explicit `name` are never swept.
+ */
+export const isGeneratedName = (name: string | undefined): boolean =>
+  name !== undefined && /-[a-z2-7]{16}$/.test(name);
+
+/**
+ * An environment by name, or a `Modal.Environment` (yielded: `yield* Agents`)
+ * whose name is used.
+ */
+export type EnvironmentInput = string | { readonly name: string };
+
+/** The environment name an {@link EnvironmentInput} resolved to. */
+export const envNameOf = (value: unknown): string | undefined =>
+  typeof value === "string"
+    ? value || undefined
+    : typeof value === "object" &&
+        value !== null &&
+        "name" in value &&
+        typeof value.name === "string"
+      ? value.name
+      : undefined;
+
+/** A protobuf `Timestamp` (RFC 3339) for a `Date`, ISO string or epoch milliseconds. */
+export const timestampOf = (value: Date | string | number): string =>
+  typeof value === "string" ? value : new Date(value).toISOString();
+
+/**
+ * Resolve a record of distilled operations into their call functions, like
+ * `Effect.all` over Effects. An operation is yieldable (`yield* op` captures
+ * the current context and returns a requirement-free call) but isn't an
+ * Effect value at runtime, so `Effect.all({ put: queue.putQueue })` fails.
+ *
+ * @example
+ * ```ts
+ * const QueueOps = operations({ put: queue.putQueue, get: queue.getQueue });
+ * const { put } = yield* ModalBindings.withCredentials(QueueOps);
+ * ```
+ */
+export const operations = <
+  const Ops extends Record<string, Effect.Effect<unknown, never, OperationServices>>,
+>(
+  ops: Ops,
+): Effect.Effect<{ readonly [K in keyof Ops]: Effect.Success<Ops[K]> }, never, OperationServices> =>
+  Effect.gen(function* () {
+    const resolved: Record<string, unknown> = {};
+    for (const [key, op] of Object.entries(ops)) resolved[key] = yield* op;
+    return resolved as { readonly [K in keyof Ops]: Effect.Success<Ops[K]> };
+  });
+
+/** The error of a resolved distilled call (or any function returning an Effect). */
+export type ErrorOf<F> = F extends (...args: any[]) => Effect.Effect<any, infer E, any> ? E : never;
+
+/** The error of operation `K` of a resolved operations record. */
+export type OpError<Ops, K extends keyof Ops> = ErrorOf<Ops[K]>;
+
+/** What a distilled Modal operation needs to run: credentials and an HTTP client. */
+export type OperationServices = Credentials | HttpClient.HttpClient;