@intentius/chant-lexicon-fly 0.124.67 → 0.124.68

package/src/op/activities/fly-apply.test.ts

@@ -43,6 +43,13 @@ import {
   flyDelete,
   toApplyResult,
   listCerts,
+  isVolumeId,
+  pickVolume,
+  resolveMountsWith,
+  volumeAliases,
+  alignMountsWithLive,
+  type FlapsVolume,
+  type FlyPlan,
   CERT_PAGE_LIMIT,
   MAX_CERT_PAGES,
   DEFAULT_FLAPS_BASE_URL,
@@ -908,11 +915,12 @@ describe("flyApply orders volumes before the machines that mount them", () => {
       writeFileSync(planPath, JSON.stringify(plan));
 
       const order: string[] = [];
+      const vols: Array<{ id: string; name: string }> = [];
       const http: FlyHttp = async (method, url) => {
         if (method === "GET" && /\/apps\/demo$/.test(url)) return { status: 404, text: "" };
         if (method === "POST" && /\/apps$/.test(url)) { order.push("app"); return { status: 200, text: "{}" }; }
-        if (method === "GET" && url.endsWith("/volumes")) return { status: 200, text: "[]" };
-        if (method === "POST" && url.endsWith("/volumes")) { order.push("volume"); return { status: 200, text: JSON.stringify({ id: "v1", name: "data" }) }; }
+        if (method === "GET" && url.endsWith("/volumes")) return { status: 200, text: JSON.stringify(vols) };
+        if (method === "POST" && url.endsWith("/volumes")) { order.push("volume"); vols.push({ id: "vol_1", name: "data" }); return { status: 200, text: JSON.stringify(vols[0]) }; }
         if (method === "GET" && url.endsWith("/machines")) return { status: 200, text: "[]" };
         if (method === "POST" && url.endsWith("/machines")) { order.push("machine"); return { status: 200, text: JSON.stringify({ id: "m1", name: "web", state: "created", instance_id: "I1", config: { image: "img:1" } }) }; }
         if (method === "GET" && url.includes("/wait")) return { status: 200, text: JSON.stringify({ ok: true }) };
@@ -930,6 +938,166 @@ describe("flyApply orders volumes before the machines that mount them", () => {
   });
 });
 
+/**
+ * #4717 — the Machines API takes a volume's id in `config.mounts[].volume`.
+ * A mount that names a volume is sent with the id of the app's live volume of
+ * that name, and the name in the mount's `name`.
+ */
+describe("a mount's volume name is sent as the volume's id (#4717)", () => {
+  const WAIT = { intervalMs: 0, deadlineMs: 5_000 };
+  const app = { endpoint: "/v1/apps", method: "POST", body: { app_name: "demo" } };
+  const volume = (name: string, region = "iad") => ({ endpoint: "/v1/apps/demo/volumes", method: "POST", body: { name, region, size_gb: 1 } });
+  const machine = (image: string, mount: Record<string, unknown>, region = "iad") => ({
+    endpoint: "/v1/apps/demo/machines",
+    method: "POST",
+    body: { name: "web", region, config: { image, mounts: [mount], metadata: { ...OWNED_META } } },
+  });
+  /** The bodies the applier POSTs to create or update a Machine. */
+  const machinePosts = (fake: ReturnType<typeof createMachinesFake>) => {
+    const posts: Array<Record<string, unknown>> = [];
+    const http: FlyHttp = async (method, url, body, headers, signal) => {
+      if (method === "POST" && /\/machines(\/[^/]+)?$/.test(new URL(url).pathname)) posts.push(body as Record<string, unknown>);
+      return fake.http(method, url, body, headers, signal);
+    };
+    return { http, posts };
+  };
+  const mountsOf = (body: Record<string, unknown> | undefined) => (body?.config as { mounts?: unknown[] } | undefined)?.mounts;
+  const vol = (id: string, name: string, extra: Partial<FlapsVolume> = {}): FlapsVolume => ({ id, name, state: "created", ...extra });
+
+  test("isVolumeId tells an id from a name", () => {
+    expect(isVolumeId("vol_r68lmz2doox9myd4")).toBe(true);
+    expect(isVolumeId("control_data")).toBe(false);
+    expect(isVolumeId("vol_")).toBe(false);
+  });
+
+  test("a volume declared in the same apply is created first and its id is mounted; a re-apply is a no-op", async () => {
+    const fake = createMachinesFake();
+    const { http, posts } = machinePosts(fake);
+    const plan: FlyPlan = { app, web: machine("img:1", { volume: "data", path: "/data" }), data: volume("data") };
+    const out = await flyApply({ plan, endpoint: CTX.base, wait: WAIT }, undefined, http);
+    expect(out.volumes).toEqual([{ app: "demo", name: "data", action: "created" }]);
+    expect(out.machines).toEqual([{ app: "demo", name: "web", action: "created" }]);
+    const [created] = fake.volumes.get("demo")!;
+    expect(created.id).toMatch(/^vol_/);
+    expect(mountsOf(posts[0])).toEqual([{ volume: created.id, name: "data", path: "/data" }]);
+    expect(fake.machine("demo", "web")!.config.mounts).toEqual([{ volume: created.id, name: "data", path: "/data" }]);
+    expect(created.attached_machine_id).toBe(fake.machine("demo", "web")!.id);
+
+    const again = await flyApply({ plan, endpoint: CTX.base, wait: WAIT }, undefined, http);
+    expect(again.machines).toEqual([{ app: "demo", name: "web", action: "noop" }]);
+    expect(posts).toHaveLength(1);
+  });
+
+  test("an update sends the id of the volume the Machine already has", async () => {
+    const fake = createMachinesFake();
+    const { http, posts } = machinePosts(fake);
+    await flyApply({ plan: { app, data: volume("data"), web: machine("img:1", { volume: "data", path: "/data" }) }, endpoint: CTX.base, wait: WAIT }, undefined, http);
+    const id = fake.volumes.get("demo")![0].id;
+    // A second volume of the same name, free in the same region: the Machine keeps its own.
+    fake.volumes.get("demo")!.push({ id: "vol_spare", name: "data", region: "iad", state: "created", attached_machine_id: null });
+
+    const out = await flyApply({ plan: { app, data: volume("data"), web: machine("img:2", { volume: "data", path: "/data" }) }, endpoint: CTX.base, wait: WAIT }, undefined, http);
+    expect(out.machines).toEqual([{ app: "demo", name: "web", action: "updated" }]);
+    expect(mountsOf(posts[1])).toEqual([{ volume: id, name: "data", path: "/data" }]);
+    expect(fake.machine("demo", "web")!.config.image).toBe("img:2");
+  });
+
+  test("a mount given an id goes through as it is, and no volume list is read for it", async () => {
+    const fake = createMachinesFake();
+    const { http, posts } = machinePosts(fake);
+    const mount = { volume: "vol_r68lmz2doox9myd4", name: "control_data", path: "/data" };
+    await flyApply({ plan: { app, web: machine("img:1", mount) }, endpoint: CTX.base, wait: WAIT }, undefined, http);
+    expect(mountsOf(posts[0])).toEqual([mount]);
+    expect(fake.calls.filter((c) => c.endsWith("/volumes"))).toEqual([]);
+  });
+
+  test("a mount naming no volume in the app fails clearly, and no Machine is posted", async () => {
+    const fake = createMachinesFake();
+    const { http, posts } = machinePosts(fake);
+    await expect(
+      flyApply({ plan: { app, logs: volume("logs"), web: machine("img:1", { volume: "data", path: "/data" }) }, endpoint: CTX.base, wait: WAIT }, undefined, http),
+    ).rejects.toThrow(/no volume named "data" in app demo .*the app's volumes: logs.*vol_\.\.\./);
+    expect(posts).toEqual([]);
+  });
+
+  test("two free volumes of the name in the Machine's region are refused, naming both", async () => {
+    const fake = createMachinesFake();
+    const { http, posts } = machinePosts(fake);
+    await flyApply({ plan: { app }, endpoint: CTX.base, wait: WAIT }, undefined, http);
+    fake.volumes.set("demo", [
+      { id: "vol_a", name: "data", region: "iad", state: "created", attached_machine_id: null },
+      { id: "vol_b", name: "data", region: "iad", state: "created", attached_machine_id: null },
+    ]);
+    await expect(
+      flyApply({ plan: { app, web: machine("img:1", { volume: "data", path: "/data" }) }, endpoint: CTX.base, wait: WAIT }, undefined, http),
+    ).rejects.toThrow(/volume name "data" is ambiguous in app demo for a new Machine in iad: 2 are free in iad \(vol_a in iad, unattached; vol_b in iad, unattached\)/);
+    expect(posts).toEqual([]);
+  });
+
+  test("of several volumes of the name, the one in the Machine's region that is free is picked", async () => {
+    const fake = createMachinesFake();
+    const { http, posts } = machinePosts(fake);
+    await flyApply({ plan: { app }, endpoint: CTX.base, wait: WAIT }, undefined, http);
+    fake.volumes.set("demo", [
+      { id: "vol_iad", name: "data", region: "iad", state: "created", attached_machine_id: null },
+      { id: "vol_ordtaken", name: "data", region: "ord", state: "created", attached_machine_id: "m-other" },
+      { id: "vol_ord", name: "data", region: "ord", state: "created", attached_machine_id: null },
+    ]);
+    await flyApply({ plan: { app, web: machine("img:1", { volume: "data", path: "/data" }, "ord") }, endpoint: CTX.base, wait: WAIT }, undefined, http);
+    expect(mountsOf(posts[0])).toEqual([{ volume: "vol_ord", name: "data", path: "/data" }]);
+  });
+
+  test("a mount naming a Volume's declaration resolves to that Volume's name, which goes in `name`", async () => {
+    const fake = createMachinesFake();
+    const { http, posts } = machinePosts(fake);
+    // A `Volume` reference serializes to the declaration's name, here `store`.
+    const plan: FlyPlan = { app, store: volume("files"), web: machine("img:1", { volume: "store", path: "/data" }) };
+    expect(volumeAliases(plan)).toEqual(new Map([["store", "files"]]));
+    await flyApply({ plan, endpoint: CTX.base, wait: WAIT }, undefined, http);
+    expect(mountsOf(posts[0])).toEqual([{ volume: fake.volumes.get("demo")![0].id, name: "files", path: "/data" }]);
+  });
+
+  test("pickVolume: the Machine's own volume first, then a free one in its region; destroyed volumes never count", () => {
+    const vols = [
+      vol("vol_mine", "data", { region: "iad", attached_machine_id: "m1" }),
+      vol("vol_free", "data", { region: "iad", attached_machine_id: null }),
+      vol("vol_gone", "data", { region: "iad", state: "pending_destroy" }),
+    ];
+    expect(pickVolume("demo", "data", vols, { machineId: "m1", region: "iad" }).id).toBe("vol_mine");
+    expect(pickVolume("demo", "data", vols, { machineId: "m2", region: "iad" }).id).toBe("vol_free");
+    expect(pickVolume("demo", "data", vols, {}).id).toBe("vol_free");
+    expect(() => pickVolume("demo", "data", [vols[2]], {})).toThrow(/no volume named "data"/);
+  });
+
+  test("pickVolume: a volume attached to another Machine, or only in another region, is refused naming it", () => {
+    expect(() => pickVolume("demo", "data", [vol("vol_x", "data", { region: "iad", attached_machine_id: "m9" })], { machineId: "m1", region: "iad" })).toThrow(
+      /ambiguous.*none is attached to Machine m1 or free in iad \(vol_x in iad, attached to m9\)/,
+    );
+    expect(() => pickVolume("demo", "data", [vol("vol_y", "data", { region: "ord" })], { region: "iad" })).toThrow(/vol_y in ord, unattached/);
+  });
+
+  test("resolveMountsWith keeps a mount's own name, passes ids and other config through, and returns config itself when nothing names a volume", () => {
+    const vols = [vol("vol_1", "data")];
+    const config = { image: "x", mounts: [{ volume: "data", name: "custom", path: "/d" }, { volume: "vol_2", path: "/e" }] };
+    expect(resolveMountsWith("demo", config, vols, {})).toEqual({
+      image: "x",
+      mounts: [{ volume: "vol_1", name: "custom", path: "/d" }, { volume: "vol_2", path: "/e" }],
+    });
+    const byId = { image: "x", mounts: [{ volume: "vol_2", path: "/e" }] };
+    expect(resolveMountsWith("demo", byId, [], {})).toBe(byId);
+    expect(resolveMountsWith("demo", undefined, [], {})).toBeUndefined();
+  });
+
+  test("alignMountsWithLive takes the live id where the live mount carries the declared name at the same path", () => {
+    const declared = { image: "x", mounts: [{ volume: "data", path: "/data" }] };
+    const live = { image: "x", mounts: [{ volume: "vol_1", name: "data", path: "/data" }] };
+    expect(configEqual(alignMountsWithLive(declared, live), live)).toBe(true);
+    const elsewhere = { image: "x", mounts: [{ volume: "vol_1", name: "data", path: "/other" }] };
+    expect(alignMountsWithLive(declared, elsewhere)).toBe(declared);
+    expect(configEqual(alignMountsWithLive({ mounts: [{ volume: "store", path: "/d" }] }, { mounts: [{ volume: "vol_1", name: "files", path: "/d" }] }, new Map([["store", "files"]])), { mounts: [{ volume: "vol_1", name: "files", path: "/d" }] })).toBe(true);
+  });
+});
+
 /**
  * #2516 — a Secret declared without a value is set outside chant. Posting it
  * as `{}` on every apply clobbered or no-oped the real secret. Apply checks the

package/src/op/activities/fly-apply.ts

@@ -26,7 +26,10 @@ import { readFileSync } from "node:fs";
 import { sleep } from "@intentius/chant/op";
 import { hasOwnershipMarker } from "@intentius/chant/ownership";
 import { FLY_METADATA_OWNERSHIP_KEYS } from "../../ownership";
+import { isVolumeId } from "../../volume-id";
 import { logProgress } from "./progress";
+
+export { isVolumeId } from "../../volume-id";
 import {
   applyResult,
   type ApplyResult,
@@ -70,7 +73,34 @@ export interface FlapsMachine {
   name: string;
   state: string;
   instance_id: string;
+  region?: string;
   config?: { metadata?: Record<string, string> } & Record<string, unknown>;
+  /** When flaps last changed the Machine, by its own clock (RFC 3339). */
+  updated_at?: string;
+  /** The status of each of the Machine's Fly checks, as the Machines API reports them (#4719). */
+  checks?: FlapsCheckStatus[];
+}
+
+/** One of a Machine's Fly checks as the Machines API reports it: `passing`, `warning` or `critical`. */
+export interface FlapsCheckStatus {
+  name: string;
+  status: string;
+  output?: string;
+  updated_at?: string;
+}
+
+/** One Machine {@link flyApply} has just created, updated or left alone. */
+export interface AppliedMachine {
+  app: string;
+  /** The plan entity that declares it. */
+  entity: string;
+  name: string;
+  id: string;
+  action: "created" | "updated" | "noop";
+  /** True when it was left unstarted (a scheduled Machine, #4696). */
+  unlaunched: boolean;
+  /** The Machine's `updated_at` as the create or update call answered it, when it changed and flaps gave one. */
+  updatedAt?: string;
 }
 
 // ── Pure helpers (unit-testable without http) ─────────────────────────────────
@@ -528,6 +558,10 @@ export async function listMachines(
  *
  * A Machine that {@link skipsLaunch} (a scheduled one, #4696) is created and
  * updated with `skip_launch: true`, and the wait is for it to rest unstarted.
+ *
+ * A mount that names a volume is sent with the volume's id (#4717), looked up
+ * among the app's live volumes ({@link pickVolume}); the comparison with the
+ * live config is made after the lookup, so an unchanged Machine stays a no-op.
  */
 export async function applyMachine(
   ctx: ApplyCtx,
@@ -536,12 +570,10 @@ export async function applyMachine(
   req: FlapsRequest,
   http: FlyHttp,
   signal?: AbortSignal,
-  opts: WaitOpts = {},
-): Promise<{ action: "created" | "updated" | "noop"; id: string; name: string }> {
+  opts: WaitOpts & { volumeAliases?: ReadonlyMap<string, string> } = {},
+): Promise<{ action: "created" | "updated" | "noop"; id: string; name: string; updatedAt?: string }> {
   const name = typeof req.body.name === "string" && req.body.name ? req.body.name : entityName;
   const unlaunched = skipsLaunch(req.body);
-  const body = { ...req.body, name, ...(unlaunched ? { skip_launch: true } : {}) };
-  const desiredConfig = req.body.config;
   const settle = (m: FlapsMachine) =>
     unlaunched
       ? waitForUnlaunched(ctx, app, m.id, m.instance_id, http, signal, opts)
@@ -549,12 +581,21 @@ export async function applyMachine(
 
   const live = (await listMachines(ctx, app, http, signal)).find((m) => m.name === name);
 
+  const region = typeof req.body.region === "string" && req.body.region ? req.body.region : live?.region;
+  const desiredConfig = await resolveMounts(ctx, app, req.body.config, { machineId: live?.id, region }, http, signal, opts.volumeAliases);
+  const body = {
+    ...req.body,
+    name,
+    ...(desiredConfig !== undefined ? { config: desiredConfig } : {}),
+    ...(unlaunched ? { skip_launch: true } : {}),
+  };
+
   if (!live) {
     const res = await http("POST", machinesUrl(ctx.base, app), body, undefined, signal);
     if (res.status >= 300) throw new Error(`machine ${app}/${name} create failed (${res.status}): ${res.text}`);
     const m = parseMachine(res.text);
     await settle(m);
-    return { action: "created", id: m.id, name };
+    return { action: "created", id: m.id, name, ...(m.updated_at ? { updatedAt: m.updated_at } : {}) };
   }
 
   if (configEqual(desiredConfig, live.config)) {
@@ -567,7 +608,7 @@ export async function applyMachine(
   if (res.status >= 300) throw new Error(`machine ${app}/${name} update failed (${res.status}): ${res.text}`);
   const m = parseMachine(res.text);
   await settle(m);
-  return { action: "updated", id: m.id, name };
+  return { action: "updated", id: m.id, name, ...(m.updated_at ? { updatedAt: m.updated_at } : {}) };
 }
 
 /** How {@link destroyMachine} treats a machine that is still running. */
@@ -738,6 +779,9 @@ export interface FlapsVolume {
   id: string;
   name: string;
   state?: string;
+  region?: string;
+  /** The Machine the volume is attached to; empty or absent when it is free. */
+  attached_machine_id?: string | null;
 }
 
 /** A live IP assignment as flaps lists it. */
@@ -783,6 +827,165 @@ export async function listVolumes(ctx: ApplyCtx, app: string, http: FlyHttp, sig
   return Array.isArray(list) ? (list as FlapsVolume[]) : [];
 }
 
+// ── Mounts: a volume's name to its id (#4717) ────────────────────────────────
+//
+// The Machines API takes a volume's id in `config.mounts[].volume`; flyctl
+// looks a name up and sends the id, with the name in the mount's `name`. A
+// chant mount may name the volume (FLY011 checks the name is declared), so the
+// applier does the same lookup right before it creates or updates a Machine.
+// The plan keeps the name: the serialized build, its digest and a release's
+// recorded config don't depend on which volume a name happens to resolve to.
+
+/** Volume states that mean the volume is going away; never a mount's target. */
+const GONE_VOLUME_STATES = new Set(["destroyed", "destroying", "pending_destroy", "scheduling_destroy"]);
+
+/** The Machine a mount is resolved for: its id once it exists, and its region. */
+export interface MountTarget {
+  machineId?: string;
+  region?: string;
+}
+
+/**
+ * Plan entity names that name a volume by its declaration, mapped to the
+ * volume's Fly name. A mount written as a `Volume` reference serializes to the
+ * declaration's name, which can differ from the volume's `name`. An entity
+ * name that is also some declared volume's `name` is left out, so a mount
+ * naming it means that volume. Pure.
+ */
+export function volumeAliases(plan: FlyPlan): Map<string, string> {
+  const named = new Map<string, string>();
+  for (const [entity, req] of Object.entries(plan)) {
+    if (!isVolumeRequest(req)) continue;
+    named.set(entity, typeof req.body.name === "string" && req.body.name ? req.body.name : entity);
+  }
+  const names = new Set(named.values());
+  const aliases = new Map<string, string>();
+  for (const [entity, name] of named) if (entity !== name && !names.has(entity)) aliases.set(entity, name);
+  return aliases;
+}
+
+/** True when a config has a mount that names its volume rather than giving its id. Pure. */
+export function mountsNeedResolving(config: unknown): boolean {
+  const mounts = (config as { mounts?: unknown } | undefined)?.mounts;
+  if (!Array.isArray(mounts)) return false;
+  return mounts.some((m) => {
+    const volume = (m as { volume?: unknown } | null)?.volume;
+    return typeof volume === "string" && volume !== "" && !isVolumeId(volume);
+  });
+}
+
+function describeVolume(v: FlapsVolume): string {
+  const where = v.region ? ` in ${v.region}` : "";
+  const attached = v.attached_machine_id ? `attached to ${v.attached_machine_id}` : "unattached";
+  return `${v.id}${where}, ${attached}`;
+}
+
+/**
+ * The volume a mount naming `name` means, for the Machine `target`. Fly lets
+ * several volumes share a name (one per Machine, often across regions), so
+ * the pick is: the volume of that name already attached to this Machine, else
+ * the one in the Machine's region that is attached to no Machine. A volume
+ * whose region or attachment flaps doesn't report counts as matching. No
+ * volume of that name, none that fits, or more than one that fits, is refused
+ * naming the candidates. Pure.
+ */
+export function pickVolume(app: string, name: string, volumes: FlapsVolume[], target: MountTarget): FlapsVolume {
+  const named = volumes.filter((v) => v.name === name && !GONE_VOLUME_STATES.has(v.state ?? ""));
+  if (named.length === 0) {
+    const others = [...new Set(volumes.filter((v) => !GONE_VOLUME_STATES.has(v.state ?? "")).map((v) => v.name))];
+    throw new Error(
+      `no volume named "${name}" in app ${app} for a Machine to mount ` +
+        `(the app's volumes: ${others.length ? others.join(", ") : "none"}). ` +
+        `Declare a Volume named "${name}", or give the mount a volume id (vol_...).`,
+    );
+  }
+  const inRegion = named.filter((v) => !target.region || !v.region || v.region === target.region);
+  const mine = target.machineId ? inRegion.filter((v) => v.attached_machine_id === target.machineId) : [];
+  const fits = mine.length > 0 ? mine : inRegion.filter((v) => !v.attached_machine_id);
+  if (fits.length === 1) return fits[0];
+  const machine = target.machineId ? `Machine ${target.machineId}` : "a new Machine";
+  const region = target.region ? ` in ${target.region}` : "";
+  const why =
+    fits.length === 0
+      ? `none is attached to ${machine} or free${region}`
+      : `${fits.length} are ${mine.length > 0 ? `attached to ${machine}` : `free${region}`}`;
+  throw new Error(
+    `volume name "${name}" is ambiguous in app ${app} for ${machine}${region}: ${why} ` +
+      `(${named.map(describeVolume).join("; ")}). Give the mount the volume's id (vol_...).`,
+  );
+}
+
+/**
+ * A Machine config with each mount that names a volume given that volume's id
+ * in `volume` and its name in `name` (a `name` the mount already has is
+ * kept). A mount with an id goes through as it is. `aliases` maps a plan's
+ * volume declaration names to volume names ({@link volumeAliases}). Returns
+ * `config` itself when no mount names a volume. Pure.
+ */
+export function resolveMountsWith<T>(
+  app: string,
+  config: T,
+  volumes: FlapsVolume[],
+  target: MountTarget,
+  aliases: ReadonlyMap<string, string> = new Map(),
+): T {
+  if (!mountsNeedResolving(config)) return config;
+  const c = config as Record<string, unknown> & { mounts: unknown[] };
+  const mounts = c.mounts.map((m) => {
+    const mount = m as Record<string, unknown>;
+    const volume = mount.volume;
+    if (typeof volume !== "string" || volume === "" || isVolumeId(volume)) return m;
+    const picked = pickVolume(app, aliases.get(volume) ?? volume, volumes, target);
+    const name = typeof mount.name === "string" && mount.name ? mount.name : picked.name;
+    return { ...mount, volume: picked.id, name };
+  });
+  return { ...c, mounts } as T;
+}
+
+/**
+ * {@link resolveMountsWith} over the app's live volumes, listed only when a
+ * mount names a volume. Volumes are listed per call, so a volume an earlier
+ * Machine in the same apply took is seen as attached.
+ */
+export async function resolveMounts<T>(
+  ctx: ApplyCtx,
+  app: string,
+  config: T,
+  target: MountTarget,
+  http: FlyHttp,
+  signal?: AbortSignal,
+  aliases?: ReadonlyMap<string, string>,
+): Promise<T> {
+  if (!mountsNeedResolving(config)) return config;
+  return resolveMountsWith(app, config, await listVolumes(ctx, app, http, signal), target, aliases);
+}
+
+/**
+ * A declared config with each mount that names a volume given the id the live
+ * config mounts at the same path, when the live mount carries that name. A
+ * read-only plan uses it to compare a declared config with a live one the way
+ * {@link applyMachine} will after it resolves the names, without listing
+ * volumes. Pure.
+ */
+export function alignMountsWithLive<T>(declared: T, live: unknown, aliases: ReadonlyMap<string, string> = new Map()): T {
+  if (!mountsNeedResolving(declared)) return declared;
+  const liveMounts = (live as { mounts?: unknown } | undefined)?.mounts;
+  if (!Array.isArray(liveMounts)) return declared;
+  const d = declared as Record<string, unknown> & { mounts: unknown[] };
+  const mounts = d.mounts.map((m) => {
+    const mount = m as Record<string, unknown>;
+    const volume = mount.volume;
+    if (typeof volume !== "string" || volume === "" || isVolumeId(volume)) return m;
+    const name = typeof mount.name === "string" && mount.name ? mount.name : aliases.get(volume) ?? volume;
+    const match = liveMounts.find((l) => {
+      const lm = l as Record<string, unknown> | null;
+      return lm?.path === mount.path && lm?.name === name && typeof lm?.volume === "string";
+    }) as Record<string, unknown> | undefined;
+    return match ? { ...mount, volume: match.volume, name } : m;
+  });
+  return mounts.every((m, i) => m === d.mounts[i]) ? declared : ({ ...d, mounts } as T);
+}
+
 /** List an app's live IP assignments (`{ ips: [...] }`). */
 export async function listIps(ctx: ApplyCtx, app: string, http: FlyHttp, signal?: AbortSignal): Promise<FlapsIp[]> {
   const res = await http("GET", ipsUrl(ctx.base, app), undefined, undefined, signal);
@@ -1061,6 +1264,13 @@ export interface FlyApplyArgs {
   force?: boolean;
   /** Wait-loop tuning (mainly for tests). */
   wait?: WaitOpts;
+  /**
+   * Called after each Machine is applied and settled, before the next one
+   * (#4719). `fly-release` waits here for the Machine's Fly checks, so a
+   * group of serving Machines rolls one at a time. A throw stops the apply
+   * there and fails it. For callers in code only; without it nothing changes.
+   */
+  afterMachine?: (machine: AppliedMachine) => Promise<void>;
 }
 
 /**
@@ -1218,8 +1428,8 @@ export async function flyApply(
     m.set(app, set);
   };
 
-  // Volumes before machines: a machine's `config.mounts[]` references a volume
-  // by name, so the volume must exist first.
+  // Volumes before machines: a machine's `config.mounts[]` names a volume,
+  // which must exist so applyMachine can send its id (#4717).
   const volumes: Array<{ app: string; name: string; action: "created" | "noop" }> = [];
   for (const [entityName, req] of volumeReqs) {
     const app = resolveApp(resourceAppSegment(req.endpoint), soleApp);
@@ -1230,13 +1440,23 @@ export async function flyApply(
   }
 
   const machines: Array<{ app: string; name: string; action: "created" | "updated" | "noop" }> = [];
+  const aliases = volumeAliases(plan);
   for (const [entityName, req] of machineReqs) {
     const app = resolveApp(machineAppSegment(req.endpoint), soleApp);
     const name = typeof req.body.name === "string" && req.body.name ? req.body.name : entityName;
     track(keepMachines, app, name);
-    const result = await applyMachine(ctx, app, entityName, req, http, signal, opts);
+    const result = await applyMachine(ctx, app, entityName, req, http, signal, { ...opts, volumeAliases: aliases });
     logProgress(`${result.action}: machine/${app}/${result.name} (${ctx.base})`);
     machines.push({ app, name: result.name, action: result.action });
+    await args.afterMachine?.({
+      app,
+      entity: entityName,
+      name: result.name,
+      id: result.id,
+      action: result.action,
+      unlaunched: skipsLaunch(req.body),
+      ...(result.updatedAt ? { updatedAt: result.updatedAt } : {}),
+    });
   }
 
   // IPs, certificates, secrets after machines (independent of them).