@alchemy.run/fly 0.0.0 → 2.0.0-beta.84

package/src/ConnectPostgres.ts

@@ -0,0 +1,68 @@
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import * as Data from "effect/Data";
+import type * as Effect from "effect/Effect";
+import type * as Redacted from "effect/Redacted";
+import type { Postgres } from "./Postgres.ts";
+
+/**
+ * Bind a {@link Postgres} cluster to a Fly {@link Service} and obtain
+ * the Effect-native connection strings for `Drizzle.Postgres` /
+ * `SQL.Postgres`. Alchemy transports the cluster's connection URIs
+ * automatically; callers do not configure connection-string env vars.
+ *
+ * `ConnectPostgres` is the Context tag, the type, and the callable —
+ * `yield* Fly.ConnectPostgres(Db)`. Provide {@link ConnectPostgresHttp}.
+ *
+ * **Example:** Bind Postgres in a Service
+ * ```typescript
+ * import * as Drizzle from "@alchemy.run/drizzle/Postgres";
+ *
+ * const conn = yield* Fly.ConnectPostgres(Db);
+ * const db = yield* Drizzle.Postgres(conn.connectionString);
+ *
+ * fetch: Effect.gen(function* () {
+ *   const rows = yield* db.select().from(users);
+ * });
+ * ```
+ *
+ * @binding
+ * @product Postgres
+ */
+export interface ConnectPostgres extends Binding.Service<
+  ConnectPostgres,
+  "Fly.ConnectPostgres",
+  (postgres: Postgres) => Effect.Effect<ConnectPostgresClient>
+> {}
+
+export const ConnectPostgres = Binding.Service<ConnectPostgres>("Fly.ConnectPostgres");
+
+export const connectEnvKeys = (postgres: Pick<Postgres, "LogicalId">) => {
+  const id = postgres.LogicalId.replaceAll(/[^a-zA-Z0-9]/g, "_").toUpperCase();
+  return {
+    pooled: `FLY_POSTGRES_${id}_POOLED`,
+    direct: `FLY_POSTGRES_${id}_DIRECT`,
+  };
+};
+
+export class PostgresUrlMissing extends Data.TaggedError("Fly.PostgresUrlMissing")<{
+  name: string;
+}> {}
+
+export interface ConnectPostgresClient {
+  /**
+   * Pooled PgBouncer connection string. Pass this to
+   * {@link Drizzle.Postgres} or `SQL.Postgres`.
+   */
+  connectionString: Effect.Effect<Redacted.Redacted<string>, PostgresUrlMissing, RuntimeContext>;
+  /**
+   * Direct (non-PgBouncer) connection string. Use this for session-scoped
+   * features (advisory locks, `LISTEN/NOTIFY`) when you are not going
+   * through the pooled URL.
+   */
+  directConnectionString: Effect.Effect<
+    Redacted.Redacted<string>,
+    PostgresUrlMissing,
+    RuntimeContext
+  >;
+}

package/src/ConnectPostgresHttp.ts

@@ -0,0 +1,77 @@
+import * as Binding from "alchemy/Binding";
+import type { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import {
+  ConnectPostgres,
+  PostgresUrlMissing,
+  type ConnectPostgresClient,
+} from "./ConnectPostgres.ts";
+import type { ServiceBinding } from "./MountVolume.ts";
+import { type Postgres } from "./Postgres.ts";
+
+const isFlyHost = (value: unknown): value is Resource<string, any, any, ServiceBinding> =>
+  typeof value === "object" &&
+  value !== null &&
+  ((value as { Type?: string }).Type === "Fly.Service" ||
+    (value as { Type?: string }).Type === "Fly.Machine");
+
+const asRedactedUrl = (
+  value: unknown,
+  name: string,
+): Effect.Effect<Redacted.Redacted<string>, PostgresUrlMissing> => {
+  const plain =
+    typeof value === "string" ? value : Redacted.isRedacted(value) ? Redacted.value(value) : "";
+  const url = typeof plain === "string" ? plain : "";
+  return url.length > 0
+    ? Effect.succeed(Redacted.make(url))
+    : Effect.fail(new PostgresUrlMissing({ name }));
+};
+
+/**
+ * Implementation of {@link ConnectPostgres}. Provide it on the
+ * {@link Service} Effect.
+ *
+ * Registers the cluster attachment for Fly's private network. Alchemy
+ * transports each cluster's connection URIs through resource Outputs,
+ * so callers do not configure connection-string environment variables.
+ *
+ *
+ * ### Provide the layer
+ * **Example:** On a Service
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const conn = yield* Fly.ConnectPostgres(Db);
+ *   const db = yield* Drizzle.Postgres(conn.connectionString);
+ * }).pipe(Effect.provide(Fly.ConnectPostgresHttp))
+ * ```
+ *
+ * @layer
+ * @product Postgres
+ * @provides Fly.ConnectPostgres
+ */
+export const ConnectPostgresHttp = Layer.effect(
+  ConnectPostgres,
+  Effect.succeed(
+    Effect.fn(function* (postgres: Postgres) {
+      const name = postgres.LogicalId;
+      if (!globalThis.__ALCHEMY_RUNTIME__) {
+        const host = yield* Binding.Host;
+        if (isFlyHost(host)) {
+          yield* host.bind`${postgres}`({
+            postgres: { clusterId: postgres.clusterId },
+          });
+        }
+      }
+
+      const pooled = yield* postgres.pooledConnectionUri;
+      const direct = yield* postgres.connectionUri;
+
+      return {
+        connectionString: pooled.pipe(Effect.flatMap((value) => asRedactedUrl(value, name))),
+        directConnectionString: direct.pipe(Effect.flatMap((value) => asRedactedUrl(value, name))),
+      } satisfies ConnectPostgresClient;
+    }),
+  ),
+);

package/src/Contributions.ts

@@ -0,0 +1,9 @@
+import * as Contributions from "alchemy/Contributions";
+
+export default Contributions.make({
+  name: "fly",
+  auth: Contributions.lazy(
+    () => import("./AuthProvider.ts"),
+    (module) => module.FlyAuth,
+  ),
+});

package/src/Credentials.ts

@@ -0,0 +1,102 @@
+import { ConfigError } from "@distilled.cloud/core/errors";
+import { Credentials, CredentialsFromEnv } from "@distilled.cloud/fly-io";
+import {
+  deferUntilFirstUse,
+  orDieCredentialsUnavailable,
+  resolveProviderConfig,
+} from "alchemy/Auth/Resolve";
+import * as Output from "alchemy/Output";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Redacted from "effect/Redacted";
+import {
+  FLY_AUTH_PROVIDER_NAME,
+  type FlyAuthConfig,
+  type FlyResolvedCredentials,
+} from "./AuthProvider.ts";
+
+export {
+  Credentials,
+  CredentialsFromEnv,
+  credentials,
+  DEFAULT_API_BASE_URL,
+  normalizeApiBaseUrl,
+  type Config as CredentialsConfig,
+} from "@distilled.cloud/fly-io";
+
+/**
+ * Capture the deployment's org token as a named runtime Output.
+ * Resolve it during binding initialization so plan/diff retains
+ * profile-backed credentials rather than falling back to process env.
+ */
+export const bindFlyApiToken = (): Effect.Effect<void, never, Credentials> =>
+  Effect.gen(function* () {
+    const token = globalThis.__ALCHEMY_RUNTIME__
+      ? ""
+      : yield* Credentials.pipe(
+          Effect.flatMap((resolve) => resolve),
+          Effect.map((cfg) => Redacted.value(cfg.apiKey)),
+        );
+    yield* Output.named(Output.asOutput(token), "FLY_API_TOKEN").asEffect().pipe(Effect.asVoid);
+  });
+
+/**
+ * `Credentials` for the HTTP binding layers (`GetSecretHttp`, `ExecHttp`, …).
+ *
+ * Those layers are built in two places. Inside a stack (plan/deploy, or an
+ * Action) `providers()` has already resolved the profile-backed
+ * `Credentials`, and the binding must use them — a laptop deploy has no
+ * `FLY_API_TOKEN` in its env once the token lives in the Alchemy profile.
+ * Inside a deployed Machine there is no profile; `bindFlyApiToken`
+ * has already `RuntimeContext.set` the org token, which Platform copies
+ * into Machine env as `FLY_API_TOKEN`. So: reuse the ambient
+ * `Credentials` when present, otherwise read the env.
+ */
+export const CredentialsFromAmbientOrEnv: Layer.Layer<Credentials> = Layer.effect(
+  Credentials,
+  Effect.gen(function* () {
+    const ambient = yield* Effect.serviceOption(Credentials);
+    if (Option.isSome(ambient)) return ambient.value;
+    return yield* Credentials.pipe(Effect.provide(CredentialsFromEnv));
+  }),
+);
+
+/**
+ * Build a `Credentials` layer that resolves Fly credentials via the current
+ * Alchemy profile, or directly from environment variables in CI.
+ *
+ * Maps onto `@distilled.cloud/fly-io`'s `{ apiKey, apiBaseUrl }` shape.
+ * Distilled's own `CredentialsFromEnv` also accepts `FLY_IO_API_KEY` as a
+ * fallback — Alchemy itself only reads `FLY_API_TOKEN`.
+ */
+export const fromAuthProvider = () =>
+  Layer.effect(
+    Credentials,
+    Effect.gen(function* () {
+      // Defer profile lookup and credential resolution until first use, so
+      // building the provider layers never requires a configured profile.
+      const resolve = yield* resolveProviderConfig<FlyAuthConfig, FlyResolvedCredentials>(
+        FLY_AUTH_PROVIDER_NAME,
+      ).pipe(
+        Effect.flatMap(({ profileName, resolve }) =>
+          resolve.pipe(
+            Effect.map((creds) => ({
+              apiKey: creds.apiKey,
+              apiBaseUrl: creds.apiBaseUrl,
+            })),
+            Effect.mapError((e) =>
+              ConfigError.make({
+                message: `Failed to resolve Fly credentials from ${profileName === undefined ? "the CI environment" : `profile '${profileName}'`}: ${(e as { message?: string }).message ?? String(e)}`,
+              }),
+            ),
+          ),
+        ),
+        deferUntilFirstUse,
+      );
+      return yield* resolve.pipe(
+        orDieCredentialsUnavailable(FLY_AUTH_PROVIDER_NAME),
+        Effect.cached,
+      );
+    }),
+  );

package/src/Decrypt.ts

@@ -0,0 +1,62 @@
+import type { DecryptSecretKeyError } from "@distilled.cloud/fly-io/machines";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type * as Redacted from "effect/Redacted";
+import type { SecretKey } from "./SecretKey.ts";
+
+export interface DecryptRequest {
+  /** Ciphertext produced by {@link Encrypt}. */
+  ciphertext: Uint8Array | ArrayLike<number>;
+  /** Optional AEAD associated data. Must match encryption. */
+  associatedData?: Uint8Array | ArrayLike<number>;
+}
+
+export interface DecryptResult {
+  /** Plaintext, wrapped so it never logs. Unwrap with `Redacted.value`. */
+  plaintext: Redacted.Redacted<Uint8Array>;
+}
+
+/**
+ * Decrypt with a Fly {@link SecretKey}. The App and key name are fixed
+ * by `Decrypt(key)`.
+ *
+ *
+ * ### Decrypt a payload
+ * Provide {@link DecryptHttp}. Plaintext comes back `Redacted`. Unwrap
+ * with `Redacted.value` only where you need the raw bytes.
+ *
+ * **Example:** Decrypt
+ * ```typescript
+ * import * as Redacted from "effect/Redacted";
+ *
+ * const decrypt = yield* Fly.Decrypt(Box);
+ * const { plaintext } = yield* decrypt({ ciphertext });
+ * const bytes = Redacted.value(plaintext);
+ * ```
+ *
+ * ### Associated data
+ * `associatedData` must match the bytes passed to {@link Encrypt}.
+ *
+ * **Example:** AEAD
+ * ```typescript
+ * const { plaintext } = yield* decrypt({
+ *   ciphertext,
+ *   associatedData: nonce,
+ * });
+ * ```
+ *
+ * @binding
+ * @product Secret Key
+ */
+export interface Decrypt extends Binding.Service<
+  Decrypt,
+  "Fly.Decrypt",
+  (
+    key: SecretKey,
+  ) => Effect.Effect<
+    (request: DecryptRequest) => Effect.Effect<DecryptResult, DecryptSecretKeyError, RuntimeContext>
+  >
+> {}
+
+export const Decrypt = Binding.Service<Decrypt>("Fly.Decrypt");

package/src/DecryptHttp.ts

@@ -0,0 +1,52 @@
+import * as machines from "@distilled.cloud/fly-io/machines";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import { CredentialsFromAmbientOrEnv } from "./Credentials.ts";
+import { Decrypt, type DecryptRequest } from "./Decrypt.ts";
+import { unwrapSecretValue } from "./SecretHttp.ts";
+import { base64ToBytes, bytesToBase64, makeHttpSecretKeyBinding } from "./SecretKeyHttp.ts";
+
+/**
+ * HTTP implementation of {@link Decrypt}. Provide it on the
+ * {@link Service} or Action Effect.
+ *
+ *
+ * ### Provide the layer
+ * **Example:** On a Service
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const decrypt = yield* Fly.Decrypt(Box);
+ *   // ...
+ * }).pipe(Effect.provide(Fly.DecryptHttp))
+ * ```
+ *
+ * @layer
+ * @product Secret Key
+ * @provides Fly.Decrypt
+ */
+export const DecryptHttp = Layer.effect(
+  Decrypt,
+  Effect.suspend(() =>
+    makeHttpSecretKeyBinding({
+      makeClient: (auth, appName, secretName) =>
+        Effect.fn("Fly.Decrypt")(function* (request: DecryptRequest) {
+          const res = yield* auth.authorize(
+            machines.decryptSecretKey({
+              app_name: yield* appName,
+              secret_name: yield* secretName,
+              ciphertext: bytesToBase64(request.ciphertext),
+              associated_data:
+                request.associatedData === undefined
+                  ? undefined
+                  : bytesToBase64(request.associatedData),
+            }),
+          );
+          return {
+            plaintext: Redacted.make(base64ToBytes(unwrapSecretValue(res.plaintext ?? ""))),
+          };
+        }),
+    }),
+  ),
+).pipe(Layer.provide(FetchHttpClient.layer), Layer.provide(CredentialsFromAmbientOrEnv));

package/src/DeleteObject.ts

@@ -0,0 +1,43 @@
+import type * as S3 from "@distilled.cloud/aws/s3";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { Bucket } from "./Bucket.ts";
+import type { TigrisCredentialsMissing } from "./Errors.ts";
+
+export interface DeleteObjectRequest extends Omit<S3.DeleteObjectRequest, "Bucket"> {}
+
+/**
+ * Runtime binding for Tigris `DeleteObject` over the S3 API.
+ *
+ * Bind this operation to a {@link Bucket} in Service init. Provide
+ * {@link DeleteObjectHttp}.
+ *
+ *
+ * ### Deleting Objects
+ * **Example:** Delete an Object
+ * ```typescript
+ * const deleteObject = yield* Fly.DeleteObject(Data);
+ * yield* deleteObject({ Key: "hello.txt" });
+ * ```
+ *
+ * @binding
+ * @product Bucket
+ */
+export interface DeleteObject extends Binding.Service<
+  DeleteObject,
+  "Fly.DeleteObject",
+  (
+    bucket: Bucket,
+  ) => Effect.Effect<
+    (
+      request: DeleteObjectRequest,
+    ) => Effect.Effect<
+      S3.DeleteObjectOutput,
+      S3.DeleteObjectError | TigrisCredentialsMissing,
+      RuntimeContext
+    >
+  >
+> {}
+
+export const DeleteObject = Binding.Service<DeleteObject>("Fly.DeleteObject");

package/src/DeleteObjectHttp.ts

@@ -0,0 +1,20 @@
+import * as S3 from "@distilled.cloud/aws/s3";
+import * as Layer from "effect/Layer";
+import { makeTigrisS3Binding } from "./BucketBinding.ts";
+import { DeleteObject } from "./DeleteObject.ts";
+
+/**
+ * HTTP implementation of {@link DeleteObject}. Calls distilled S3
+ * `deleteObject` against the Tigris endpoint with the bucket's credentials.
+ *
+ * @layer
+ * @product Bucket
+ * @provides Fly.DeleteObject
+ */
+export const DeleteObjectHttp = Layer.effect(
+  DeleteObject,
+  makeTigrisS3Binding({
+    tag: "Fly.DeleteObject",
+    operation: S3.deleteObject,
+  }),
+);

package/src/Deployment.ts

@@ -0,0 +1,121 @@
+import type { FlyMachineConfig, FlyStopConfigSignal } from "@distilled.cloud/fly-io/machines";
+import * as Data from "effect/Data";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import { pinsFromConfig } from "./DeploymentImages.ts";
+import type { MachineServiceCheck } from "./Machine.ts";
+
+/** Replacement/readiness policy shared by Machines, Services, and websites; not an App-wide deployment lock. */
+export interface MachineDeploy {
+  /** Sequential in-place updates, or a checked replacement set. @default "rolling" */
+  strategy: "rolling" | "bluegreen";
+  /** Readiness deadline after startup, positive and at most 300 seconds. A deadline-only change does not replace Machines. @default "60 seconds" */
+  healthTimeout?: Duration.Input;
+}
+
+/** Process shutdown policy. Retirement uses the predecessor's own policy; raw images and external website servers own signal handling and drain. */
+export interface MachineShutdown {
+  /** Signal sent before termination. Managed Services support SIGTERM and SIGINT. @default "SIGTERM" */
+  signal?: Exclude<FlyStopConfigSignal, "SIGKILL">;
+  /** Grace period, greater than zero and at most 300 seconds. @default "30 seconds" */
+  timeout?: Duration.Input;
+}
+
+/** Named readiness check for a worker without public proxy ports. */
+export interface MachineCheck extends MachineServiceCheck {
+  /** Port inside the Machine to check. */
+  port: number;
+}
+
+export class InvalidDeployment extends Data.TaggedError("Fly.InvalidDeployment")<{
+  message: string;
+}> {}
+
+export interface DeploymentPolicy {
+  bluegreen: boolean;
+  healthTimeoutMs: number;
+  shutdown:
+    | { signal: Exclude<FlyStopConfigSignal, "SIGKILL">; timeout: string; timeoutMs: number }
+    | undefined;
+}
+
+const duration = (value: Duration.Input, name: string, maximum: number) =>
+  Effect.try({
+    try: () => {
+      const milliseconds = Duration.toMillis(value);
+      if (!Number.isSafeInteger(milliseconds) || milliseconds <= 0 || milliseconds > maximum) {
+        throw new Error("invalid duration");
+      }
+      return milliseconds;
+    },
+    catch: () =>
+      new InvalidDeployment({
+        message: `${name} must be a finite positive duration no greater than ${maximum / 1000} seconds.`,
+      }),
+  });
+
+export const deploymentPolicy = Effect.fn(function* (
+  deploy: MachineDeploy | undefined,
+  shutdown: MachineShutdown | undefined,
+  managed = false,
+) {
+  const bluegreen = deploy?.strategy === "bluegreen";
+  const healthTimeoutMs = yield* duration(
+    deploy?.healthTimeout ?? "60 seconds",
+    "deploy.healthTimeout",
+    300_000,
+  );
+  const enabled = bluegreen || shutdown !== undefined;
+  const signal = shutdown?.signal ?? "SIGTERM";
+  if (
+    enabled &&
+    !["SIGHUP", "SIGINT", "SIGQUIT", "SIGUSR1", "SIGUSR2", "SIGTERM"].includes(signal)
+  ) {
+    return yield* new InvalidDeployment({
+      message: "shutdown.signal must be a supported graceful Fly signal, not SIGKILL.",
+    });
+  }
+  if (managed && enabled && signal !== "SIGTERM" && signal !== "SIGINT") {
+    return yield* new InvalidDeployment({
+      message: "Managed Fly Services support SIGTERM and SIGINT shutdown signals.",
+    });
+  }
+  const timeoutMs = enabled
+    ? yield* duration(shutdown?.timeout ?? "30 seconds", "shutdown.timeout", 300_000)
+    : undefined;
+  return {
+    bluegreen,
+    healthTimeoutMs,
+    shutdown:
+      timeoutMs === undefined ? undefined : { signal, timeout: `${timeoutMs}ms`, timeoutMs },
+  } satisfies DeploymentPolicy;
+});
+
+export const validateDeployment = (
+  policy: DeploymentPolicy,
+  config: FlyMachineConfig,
+  mounted: boolean,
+  skipLaunch = false,
+) => {
+  if (!policy.bluegreen) return Effect.void;
+  let message: string | undefined;
+  if (mounted)
+    message = "Blue/green deployments cannot attach volumes, including MountVolume bindings.";
+  else if (config.containers !== undefined && pinsFromConfig(config) === undefined)
+    message =
+      "Blue/green multi-container Machines require unique names and immutable repository@sha256 image references for every container.";
+  else if (skipLaunch || config.auto_destroy || config.restart?.policy === "no")
+    message = "Blue/green deployments require a persistent, launched Machine.";
+  else if (
+    (config.services ?? []).some(
+      (service) => (service.ports?.length ?? 0) > 0 && !service.checks?.length,
+    )
+  )
+    message = "Every published service needs a service health check for blue/green deployment.";
+  else if (
+    !(config.services ?? []).some((service) => service.checks?.length) &&
+    !Object.keys(config.checks ?? {}).length
+  )
+    message = "Blue/green deployments require readiness checks.";
+  return message ? Effect.fail(new InvalidDeployment({ message })) : Effect.void;
+};

package/src/DeploymentImages.ts

@@ -0,0 +1,84 @@
+import type { FlyMachineConfig } from "@distilled.cloud/fly-io/machines";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { alchemyMetadataKeys as keys } from "./Metadata.ts";
+
+const ImageSet = Schema.Array(Schema.Struct({ name: Schema.String, image: Schema.String }));
+export type ContainerImagePin = { name: string; image: string };
+
+/** Blue/green needs immutable image references that survive a crash. */
+export const isImmutableImage = (image: string): boolean =>
+  /^[a-zA-Z0-9][a-zA-Z0-9._:/-]*@sha256:[a-fA-F0-9]{64}$/.test(image);
+
+const canonical = (pins: readonly ContainerImagePin[]): ContainerImagePin[] =>
+  [...pins].sort((a, b) => a.name.localeCompare(b.name));
+
+const valid = (pins: readonly ContainerImagePin[]): boolean =>
+  pins.length > 0 &&
+  new Set(pins.map(({ name }) => name)).size === pins.length &&
+  pins.every(({ name, image }) => name.trim().length > 0 && isImmutableImage(image));
+
+export const pinsFromConfig = (
+  config: FlyMachineConfig | undefined,
+): ContainerImagePin[] | undefined => {
+  const containers = config?.containers;
+  if (!containers?.length) return undefined;
+  const pins = containers.map(({ name, image }) => ({
+    name: name ?? "",
+    image: image ?? "",
+  }));
+  return valid(pins) ? canonical(pins) : undefined;
+};
+
+export const encodeImageSet = (pins: readonly ContainerImagePin[]): string | undefined =>
+  valid(pins) ? JSON.stringify(canonical(pins)) : undefined;
+
+export const decodeImageSet = (raw: string | undefined): ContainerImagePin[] | undefined => {
+  if (raw === undefined) return undefined;
+  const decoded = Schema.decodeUnknownOption(Schema.fromJsonString(ImageSet))(raw);
+  if (!Option.isSome(decoded)) return undefined;
+  const pins = decoded.value;
+  return valid(pins) ? canonical(pins) : undefined;
+};
+
+export const sameImageSet = (
+  left: readonly ContainerImagePin[] | undefined,
+  right: readonly ContainerImagePin[] | undefined,
+): boolean => {
+  const a = left === undefined ? undefined : encodeImageSet(left);
+  const b = right === undefined ? undefined : encodeImageSet(right);
+  return a !== undefined && b !== undefined && a === b;
+};
+
+/** Protocol-2 metadata and the authoritative readback config must describe exactly the same set. */
+export const validObservedImageSet = (machine: { config?: FlyMachineConfig }): boolean => {
+  const metadata = machine.config?.metadata;
+  if (metadata?.[keys.protocol] !== "2" || metadata[keys.image] !== undefined) return false;
+  return sameImageSet(
+    decodeImageSet(metadata[keys.containerImageSet]),
+    pinsFromConfig(machine.config),
+  );
+};
+
+/** Keep all named pins when changing service or idle policy on a candidate. */
+export const applyImageSet = (
+  config: FlyMachineConfig,
+  pins: readonly ContainerImagePin[],
+): FlyMachineConfig | undefined => {
+  if (!valid(pins) || !config.containers) return undefined;
+  const byName = new Map(pins.map((pin) => [pin.name, pin.image]));
+  if (
+    config.containers.length !== byName.size ||
+    new Set(config.containers.map(({ name }) => name)).size !== config.containers.length ||
+    config.containers.some(({ name }) => name === undefined || !byName.has(name))
+  )
+    return undefined;
+  return {
+    ...config,
+    image: undefined,
+    containers: config.containers.map((container) => ({
+      ...container,
+      image: byName.get(container.name!),
+    })),
+  };
+};