@intentius/chant-lexicon-fly 0.124.67 → 0.124.69

package/README.md

@@ -85,7 +85,7 @@ Lint rules run during `chant build`, before anything reaches the API:
 
 - `region` must be a real Fly region.
 - Guest sizing (`cpu_kind` / `cpus` / `memory_mb`) must be a valid combination.
-- Every machine mount must reference a `Volume` declared in the stack, checked across files.
+- Every machine mount must reference a `Volume` declared in the stack, checked across files, or give an existing volume's id (`vol_...`).
 - Secret values may not be written inline; they belong in a `Secret` or a reference.
 
 ## The deploy Op

package/dist/components/fly-release.d.ts

@@ -29,8 +29,19 @@
  * 3. verify: the Machine is started with this release, and its health
  *    endpoint answers when a URL is given;
  * 4. on a failure after the Machine changed, restore: the config it replaced
- *    goes back (or, on a first release, the Machine is stopped), and the step
- *    fails.
+ *    goes back (or, on a first release, the Machine is stopped), and so does
+ *    the old config of each other Machine the release updated, and the step
+ *    fails. A failure partway through the apply restores the Machines it had
+ *    already updated the same way.
+ *
+ * Given `checks` (#4719), the apply rolls the plan's Machines one at a time on
+ * their Fly checks: each Machine it starts must pass its checks
+ * (`checks[].status` on the Machine, reported since its update) before the
+ * next is updated, within `checks.timeoutMs` (default five minutes). A Machine
+ * with no checks is done once started. Verify then also needs every Machine
+ * the release started to pass its checks, and a failure restores the Machines
+ * the release changed last changed first, each restore waiting for its
+ * Machine's checks. Without `checks`, only `started` is waited for.
  *
  * A scheduled Machine (`config.schedule`, #4696) is released without being
  * started, whether it is the one that serves or another Machine in the plan:
@@ -53,7 +64,7 @@
  */
 import type { Capability, DeployContext } from "@intentius/chant/components/capability";
 import type { ReceiptStore, EffectReceiptRef } from "@intentius/chant/op/receipt-store";
-import { type MachineFile, type MachineRelease } from "../op/activities/machine-release.js";
+import { type MachineChecksOpts, type MachineFile, type MachineRelease } from "../op/activities/machine-release.js";
 import { type FlyHttp, type WaitOpts } from "../op/activities/fly-apply.js";
 import type { MachineConfigStore } from "../release-store.js";
 import { type ReleaseIdentity } from "@intentius/chant/telemetry-attribution";
@@ -126,6 +137,14 @@ export interface FlyReleaseInput {
     /** Migrations, in order. */
     migrations?: FlyMigration[];
     verify?: FlyVerify;
+    /**
+     * Roll the Machines one at a time on their Fly checks (#4719): each Machine
+     * the release starts must pass its checks before the next is updated, and
+     * verify reads every one's checks. `true` takes the defaults: five minutes
+     * per Machine, polled every second. A Machine with no checks configured is
+     * done once started. Without it, only `started` is waited for.
+     */
+    checks?: MachineChecksOpts | true;
     /** flaps endpoint override. Default: `FLY_FLAPS_BASE_URL`, else real Fly. */
     endpoint?: string;
     wait?: WaitOpts;

package/dist/components/fly-release.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fly-release.d.ts","sourceRoot":"","sources":["../../src/components/fly-release.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fly-release.d.ts","sourceRoot":"","sources":["../../src/components/fly-release.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AACxF,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AACxF,OAAO,EAaL,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,cAAc,EAEpB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAA4E,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACnJ,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAE3D,OAAO,EAA2B,KAAK,eAAe,EAAE,MAAM,wCAAwC,CAAC;AAEvG,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAC3B,4HAA4H;IAC5H,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACxB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6FAA6F;IAC7F,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;CAC1B;AAED,8GAA8G;AAC9G,eAAO,MAAM,kBAAkB,QAAc,CAAC;AAkB9C,kGAAkG;AAClG,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAW5G;AAID,6CAA6C;AAC7C,MAAM,WAAW,SAAS;IACxB,2FAA2F;IAC3F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,kHAAkH;IAClH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAC5B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,yEAAyE;IACzE,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAChC,qDAAqD;IACrD,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,gGAAgG;AAChG,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACtC,+BAA+B;IAC/B,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;CACjC;AAED,oGAAoG;AACpG,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,gGAAgG;IAChG,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACvF,qFAAqF;IACrF,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC5E,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAmBD,qDAAqD;AACrD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,GAAG;IAAE,GAAG,EAAE,gBAAgB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAMrH;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CASzG;AASD,0CAA0C;AAC1C,wBAAgB,0BAA0B,CAAC,IAAI,GAAE,cAAmB,GAAG,UAAU,CAAC,eAAe,EAAE,gBAAgB,CAAC,CAkMnH;AAED,2CAA2C;AAC3C,wBAAgB,2BAA2B,CAAC,IAAI,GAAE,cAAmB,GAAG,UAAU,CAAC,gBAAgB,EAAE,iBAAiB,CAAC,CA4DtH;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWrH;AAED,4CAA4C;AAC5C,eAAO,MAAM,oBAAoB,+CAA+B,CAAC;AACjE,6CAA6C;AAC7C,eAAO,MAAM,qBAAqB,iDAAgC,CAAC"}

package/dist/components/fly-release.js

@@ -29,8 +29,19 @@
  * 3. verify: the Machine is started with this release, and its health
  *    endpoint answers when a URL is given;
  * 4. on a failure after the Machine changed, restore: the config it replaced
- *    goes back (or, on a first release, the Machine is stopped), and the step
- *    fails.
+ *    goes back (or, on a first release, the Machine is stopped), and so does
+ *    the old config of each other Machine the release updated, and the step
+ *    fails. A failure partway through the apply restores the Machines it had
+ *    already updated the same way.
+ *
+ * Given `checks` (#4719), the apply rolls the plan's Machines one at a time on
+ * their Fly checks: each Machine it starts must pass its checks
+ * (`checks[].status` on the Machine, reported since its update) before the
+ * next is updated, within `checks.timeoutMs` (default five minutes). A Machine
+ * with no checks is done once started. Verify then also needs every Machine
+ * the release started to pass its checks, and a failure restores the Machines
+ * the release changed last changed first, each restore waiting for its
+ * Machine's checks. Without `checks`, only `started` is waited for.
  *
  * A scheduled Machine (`config.schedule`, #4696) is released without being
  * started, whether it is the one that serves or another Machine in the plan:
@@ -52,7 +63,7 @@
  * call and refuses a recorded config that does not carry exactly that tree.
  */
 import { createHash } from "node:crypto";
-import { findMachine, flyMachineExec, flyMachineRelease, flyMachineRestart, flyMachineRestore, flyMachineStop, flyMachineVerify, readMachineRelease, releaseTarget, } from "../op/activities/machine-release.js";
+import { findMachine, flyMachineChecks, flyMachineExec, flyMachineRelease, flyMachineRestart, flyMachineRestore, flyMachineStop, flyMachineVerify, readMachineRelease, releaseTarget, MachineReleaseError, } from "../op/activities/machine-release.js";
 import { defaultFlyHttp, machineSchedule, parsePlan, resolveEndpoint, skipsLaunch } from "../op/activities/fly-apply.js";
 import { readFileSync } from "node:fs";
 import { releaseAttributesSuffix } from "@intentius/chant/telemetry-attribution";
@@ -139,17 +150,36 @@ const uriOf = (app, machine) => `fly://${app}/${machine}`;
 export function createFlyReleaseCapability(deps = {}) {
     const log = deps.log ?? ((line) => console.error(line));
     const httpFor = () => deps.http ?? defaultFlyHttp();
-    /** On a failed release, put the plan's other Machines it updated back on their old configs. */
-    async function restoreOthers(released, input, http) {
-        for (const other of released.others) {
-            if (other.action !== "updated" || !other.previous)
+    /**
+     * On a failed release, put each Machine it changed back. The serving
+     * Machine gets its old config, or is stopped when it served nothing before;
+     * another Machine it updated gets its old config.
+     *
+     * Without `checks` this is the order and the calls fly-release made before
+     * #4719: the serving Machine first, then the others in plan order. With
+     * `checks`, the last Machine changed goes back first, and each restore
+     * waits for its Machine's checks before the next.
+     */
+    async function restoreApplied(applied, input, http, rolling, servingWas) {
+        const order = rolling ? [...applied].reverse() : [...applied.filter((m) => m.serving), ...applied.filter((m) => !m.serving)];
+        for (const m of order) {
+            if (m.serving ? rolling && m.action === "noop" : m.action !== "updated" || !m.previous)
                 continue;
+            const where = { app: m.app, machine: m.name, endpoint: input.endpoint, wait: input.wait };
             try {
-                await flyMachineRestore({ app: other.app, machine: other.name, config: other.previous, endpoint: input.endpoint, wait: input.wait }, undefined, http);
-                log(`fly-release: restored ${other.app}/${other.name} to its previous config`);
+                if (m.previous) {
+                    await flyMachineRestore({ ...where, config: m.previous, ...(rolling ? { checks: rolling } : {}) }, undefined, http);
+                    const was = m.serving ? (servingWas === undefined ? readMachineRelease(m.previous.metadata)?.digest : (servingWas ?? undefined)) : undefined;
+                    log(`fly-release: restored ${m.app}/${m.name} to ${was ?? "its previous config"}`);
+                }
+                else {
+                    await flyMachineStop(where, undefined, http);
+                    log(`fly-release: nothing had been released on ${m.app}/${m.name}; stopped it`);
+                }
             }
             catch (restoreErr) {
-                log(`fly-release: restore of ${other.app}/${other.name} failed: ${restoreErr instanceof Error ? restoreErr.message : String(restoreErr)}`);
+                const why = restoreErr instanceof Error ? restoreErr.message : String(restoreErr);
+                log(m.serving && !rolling ? `fly-release: restore failed: ${why}` : `fly-release: restore of ${m.app}/${m.name} failed: ${why}`);
             }
         }
     }
@@ -203,17 +233,29 @@ export function createFlyReleaseCapability(deps = {}) {
                 ...(attributes !== undefined ? { OTEL_RESOURCE_ATTRIBUTES: attributes } : {}),
                 ...(input.env ?? {}),
             };
-            const released = await flyMachineRelease({
-                plan,
-                machine: input.machine,
-                release: { digest: input.digest, gitSha, ...(input.release ? { release: input.release } : {}) },
-                image: input.image,
-                ...(input.images ? { images: input.images } : {}),
-                env,
-                ...(source ? { files: source.files, cmd: source.cmd } : {}),
-                endpoint: input.endpoint,
-                wait: input.wait,
-            }, undefined, http);
+            const rolling = input.checks === true ? {} : input.checks;
+            let released;
+            try {
+                released = await flyMachineRelease({
+                    plan,
+                    machine: input.machine,
+                    release: { digest: input.digest, gitSha, ...(input.release ? { release: input.release } : {}) },
+                    image: input.image,
+                    ...(input.images ? { images: input.images } : {}),
+                    env,
+                    ...(source ? { files: source.files, cmd: source.cmd } : {}),
+                    endpoint: input.endpoint,
+                    wait: input.wait,
+                    ...(rolling ? { checks: rolling } : {}),
+                }, undefined, http);
+            }
+            catch (err) {
+                // A Machine failed to settle or to pass its checks partway through the
+                // roll: put back every Machine changed so far, then fail.
+                if (err instanceof MachineReleaseError)
+                    await restoreApplied(err.applied, input, http, rolling);
+                throw err;
+            }
             const where = { app: released.app, machine: released.machine.name, endpoint: input.endpoint };
             log(`fly-release: ${released.app}/${released.machine.name} ${released.action}, serving ${input.digest}${released.unlaunched ? ", stopped until its schedule starts it" : ""}`);
             for (const other of released.others) {
@@ -250,25 +292,31 @@ export function createFlyReleaseCapability(deps = {}) {
                     if (migrations.some((m) => m.fired))
                         await flyMachineRestart({ ...where, wait: input.wait }, undefined, http);
                 }
-                await flyMachineVerify({ ...where, digest: input.digest, ...(input.verify ?? {}) }, undefined, http, deps.fetch);
+                const serving = released.applied.find((m) => m.serving);
+                await flyMachineVerify({
+                    ...where,
+                    digest: input.digest,
+                    ...(input.verify ?? {}),
+                    ...(rolling ? { checks: true, ...(serving?.updatedAt ? { checksSince: serving.updatedAt } : {}) } : {}),
+                }, undefined, http, deps.fetch);
+                // With checks, every other Machine the release started serves too: started, with its checks passing.
+                for (const m of rolling ? released.applied : []) {
+                    if (m.serving || m.action === "noop" || m.unlaunched)
+                        continue;
+                    await flyMachineChecks({
+                        app: m.app,
+                        machine: m.name,
+                        endpoint: input.endpoint,
+                        timeoutMs: input.verify?.timeoutMs ?? 120000,
+                        intervalMs: input.verify?.intervalMs,
+                        ...(m.updatedAt ? { since: m.updatedAt } : {}),
+                    }, undefined, http);
+                }
             }
             catch (err) {
-                // Restore: the Machine changed, so put back what it served (or stop it
-                // when it served nothing), then fail the step.
-                try {
-                    if (released.previous) {
-                        await flyMachineRestore({ ...where, config: released.previous.config, wait: input.wait }, undefined, http);
-                        log(`fly-release: restored ${released.app}/${released.machine.name} to ${previousRelease?.digest ?? "its previous config"}`);
-                    }
-                    else {
-                        await flyMachineStop({ ...where, wait: input.wait }, undefined, http);
-                        log(`fly-release: nothing had been released on ${released.app}/${released.machine.name}; stopped it`);
-                    }
-                }
-                catch (restoreErr) {
-                    log(`fly-release: restore failed: ${restoreErr instanceof Error ? restoreErr.message : String(restoreErr)}`);
-                }
-                await restoreOthers(released, input, http);
+                // Restore: the Machines changed, so put back what each served (or stop
+                // the serving one when it served nothing), then fail the step.
+                await restoreApplied(released.applied, input, http, rolling, previousRelease?.digest ?? null);
                 throw err;
             }
             await configs.write({ app: released.app, machine: released.machine.name, digest: input.digest }, released.config);

package/dist/describe-resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAoB,MAAM,0BAA0B,CAAC;AAKtG,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAqBL,KAAK,OAAO,EAIb,MAAM,2BAA2B,CAAC;AAcnC,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA2BD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,GAC5E,MAAM,CA8BR;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,IAAI,GAAE,OAA0B,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,iBAAiB,CAAC,CA2S5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,wBAAwB,GAAG;IAClC,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACjD,EACD,IAAI,GAAE,OAA0B,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAkCrD"}
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAoB,MAAM,0BAA0B,CAAC;AAKtG,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAuBL,KAAK,OAAO,EAIb,MAAM,2BAA2B,CAAC;AAcnC,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA2BD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,GAC5E,MAAM,CA8BR;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,IAAI,GAAE,OAA0B,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,iBAAiB,CAAC,CA2S5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,wBAAwB,GAAG;IAClC,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACjD,EACD,IAAI,GAAE,OAA0B,EAChC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAuCrD"}

package/dist/describe-resources.js

@@ -31,7 +31,7 @@ import { readOwnership } from "@intentius/chant/ownership";
 import { FLY_METADATA_OWNERSHIP_KEYS } from "./ownership.js";
 import { readMachineRelease } from "./release-metadata.js";
 import { buildChangeSet, renderChangeSet, } from "@intentius/chant/lifecycle/change-set";
-import { resolveEndpoint, defaultFlyHttp, parsePlan, isAppRequest, isMachineRequest, isVolumeRequest, isIpRequest, isCertRequest, appNameFromRequest, machineAppSegment, resourceAppSegment, resolveApp, isChantOwned, configEqual, listMachines, listVolumes, listIps, listCerts, ipType, declaredIpType, } from "./op/activities/fly-apply.js";
+import { resolveEndpoint, defaultFlyHttp, parsePlan, isAppRequest, isMachineRequest, isVolumeRequest, isIpRequest, isCertRequest, appNameFromRequest, machineAppSegment, resourceAppSegment, resolveApp, isChantOwned, configEqual, alignMountsWithLive, volumeAliases, listMachines, listVolumes, listIps, listCerts, ipType, declaredIpType, } from "./op/activities/fly-apply.js";
 /** The chant entity types the fly serializer emits, for the metadata `type` field. */
 const TYPE = {
     app: "Fly::Machines::App",
@@ -419,8 +419,11 @@ export async function flyPlan(options, http = defaultFlyHttp(), signal) {
     });
     // Declared config per entity, for the machine update/noop refinement.
     const declaredConfig = new Map();
+    let aliases = new Map();
     try {
-        for (const [entityName, req] of Object.entries(parsePlan(options.buildOutput))) {
+        const plan = parsePlan(options.buildOutput);
+        aliases = volumeAliases(plan);
+        for (const [entityName, req] of Object.entries(plan)) {
             if (isMachineRequest(req))
                 declaredConfig.set(entityName, req.body.config);
         }
@@ -435,7 +438,9 @@ export async function flyPlan(options, http = defaultFlyHttp(), signal) {
         if (declaredCfg === undefined)
             continue; // not a declared machine
         const liveCfg = observedNow[entry.name]?.attributes?.config;
-        if (!configEqual(declaredCfg, liveCfg)) {
+        // A declared mount names its volume; the live one has the id flyApply
+        // looked up, and the name beside it (#4717).
+        if (!configEqual(alignMountsWithLive(declaredCfg, liveCfg, aliases), liveCfg)) {
             entry.action = "update";
         }
     }

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "11ee92fa970ded6aee7906a391726e01f76176ddd440bc7e32452b3cffea86d8",
+    "manifest.json": "30ca5e8ced397902a71529dc62b4072fc6c30488b1353ee27901ebbf4dc3174d",
     "meta.json": "273f2a523b66f08ca91642dba2592c44765ab59ddf7329998884a0b08c6c3f24",
     "types/index.d.ts": "75c29d3ba9faa7c2792a0a25c51dc13df011906ffbd4c9e3ccc80023f5f32667",
     "rules/guest-sizing.ts": "8dd2db79a47ceab3d488f84f560aed1b1e4a66b4e36bf11f3baf6a8544d6e126",
@@ -9,12 +9,12 @@
     "rules/valid-region.ts": "238afb252ffb59ef131d070a705a49a1ac87b98f6a86c029a69dc82200e1aabf",
     "rules/fly-helpers.ts": "dd29d4b520727210a56ef604a89df380f91f8b35770bc28f5c51d0f99ca92dff",
     "rules/fly010-machine-requires-image.ts": "dd9b70ee604867a9f02334013476afcf44a78b49bbba3d66296b8ccc2b02c8a0",
-    "rules/fly011-mount-references-declared-volume.ts": "4698f73b85954a4094a1445d42336698440bf99a4004c067529c5f9fa1047cc6",
+    "rules/fly011-mount-references-declared-volume.ts": "b54c4bb4d29cdd13ca3ff5e9e6e9b2870703ccbb23856c2be8f6983f6833b61e",
     "rules/fly012-machine-schedule.ts": "f94c75d64dd3888797c89da4e5dd11d95c47d45ff19a69a725cf098f705003b1",
-    "skills/chant-fly.md": "7346fd12cffcb4ce39feb0655550f47e330bf0cafc679dee1b08e4db5140969a",
-    "skills/chant-fly-patterns.md": "adc3c4432344c833e23d41ab470b7e12eb8d55e512cf856ac3ddda5b199e2a90",
-    "skills/chant-fly-ops.md": "e2ec53f55d89ffaace9183c348d80a6c2f13da3ef3ac3987a0e4f17b62264b20",
+    "skills/chant-fly.md": "a81a2f60b593f311b6553a1b4aa2578ac843f1539f9496ba58a8309ed0357196",
+    "skills/chant-fly-patterns.md": "25156b507116c988a304f77900f3c6afabf24dce45b7a9d121a8d23950d7e6cc",
+    "skills/chant-fly-ops.md": "cf25cf3ef9fb68fdb320a35c411d893d57bbf0ad4216f571aa9ce42eaebacd24",
     "skills/chant-fly-sprites.md": "3d100680422151b58d082c3a7b30a286edfc52faa4887995c9ad5553873bab95"
   },
-  "composite": "220b6c76a5ff5eee5413ed9f1c43412486cddb661ceb76842b9c5628f89a51f4"
+  "composite": "5ab19c38c1cbb14e7bae8d7f86eb9ee04eceb9b54b5ea2c16cbc09d1f00075d7"
 }

package/dist/lint/audit-catalog.js

@@ -22,7 +22,7 @@ function rule(id, tier, category, title, remediation) {
 }
 export const flyAuditCatalog = {
     FLY010: rule("FLY010", "merge-worthy", "correctness", "Machine config has no image", "Set `config.image` on the Machine — a Machine cannot boot without one."),
-    FLY011: rule("FLY011", "merge-worthy", "correctness", "Machine mount references an undeclared volume", "Declare the Volume in the same stack, or point the mount at one that is."),
+    FLY011: rule("FLY011", "merge-worthy", "correctness", "Machine mount references an undeclared volume", "Declare the Volume in the same stack, point the mount at one that is, or mount an existing volume by its id (vol_...)."),
     FLY012: rule("FLY012", "merge-worthy", "correctness", "Machine schedule is not one Fly runs", "Set `config.schedule` to `hourly`, `daily`, `weekly` or `monthly`; the Machines API takes no cron expression."),
 };
 // Prior art credits live beside the rules in ./audit-lineage.ts (see core audit/prior-art.ts).

package/dist/lint/post-synth/fly011-mount-references-declared-volume.d.ts

@@ -6,6 +6,10 @@
  * apply time, so catch it at synth. This is a whole-stack check: it reads all
  * entities in the build (`ctx.entities`), so the mount and the Volume can be
  * declared in different files.
+ *
+ * A mount given a volume id (`vol_...`) names a volume that already exists on
+ * Fly, which the stack need not declare, so it passes (#4717). `flyApply`
+ * sends it as it is, and looks a name up to send its id.
  */
 import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
 export declare const fly011: PostSynthCheck;

package/dist/lint/post-synth/fly011-mount-references-declared-volume.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fly011-mount-references-declared-volume.d.ts","sourceRoot":"","sources":["../../../src/lint/post-synth/fly011-mount-references-declared-volume.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAyC,MAAM,kCAAkC,CAAC;AAM9G,eAAO,MAAM,MAAM,EAAE,cA4CpB,CAAC"}
+{"version":3,"file":"fly011-mount-references-declared-volume.d.ts","sourceRoot":"","sources":["../../../src/lint/post-synth/fly011-mount-references-declared-volume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAyC,MAAM,kCAAkC,CAAC;AAO9G,eAAO,MAAM,MAAM,EAAE,cA8CpB,CAAC"}

package/dist/lint/post-synth/fly011-mount-references-declared-volume.js

@@ -6,13 +6,18 @@
  * apply time, so catch it at synth. This is a whole-stack check: it reads all
  * entities in the build (`ctx.entities`), so the mount and the Volume can be
  * declared in different files.
+ *
+ * A mount given a volume id (`vol_...`) names a volume that already exists on
+ * Fly, which the stack need not declare, so it passes (#4717). `flyApply`
+ * sends it as it is, and looks a name up to send its id.
  */
 import { readProps, entityTypeOf } from "./fly-helpers.js";
+import { isVolumeId } from "../../volume-id.js";
 const MACHINE_ENTITY_TYPE = "Fly::Machines::Machine";
 const VOLUME_ENTITY_TYPE = "Fly::Machines::Volume";
 export const fly011 = {
     id: "FLY011",
-    description: "A machine mount's volume must resolve to a Volume declared in the stack",
+    description: "A machine mount's volume must resolve to a Volume declared in the stack, or be a volume id (vol_...)",
     check(ctx) {
         const diagnostics = [];
         // A mount can name a declared volume by the Volume's `name` or by its
@@ -42,11 +47,14 @@ export const fly011 = {
                 // never dangles — skip it to avoid false positives.
                 if (typeof volume !== "string" || volume.length === 0)
                     continue;
+                // A volume id names a volume that exists outside the stack.
+                if (isVolumeId(volume))
+                    continue;
                 if (!declaredVolumes.has(volume)) {
                     diagnostics.push({
                         checkId: "FLY011",
                         severity: "error",
-                        message: `Machine "${machineName}" mounts volume "${volume}", which is not declared as a Volume in the stack.`,
+                        message: `Machine "${machineName}" mounts volume "${volume}", which is not declared as a Volume in the stack. Declare the Volume, or mount an existing volume by its id (vol_...).`,
                         entity: machineName,
                         lexicon: "fly",
                     });

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "fly",
-  "version": "0.124.67",
+  "version": "0.124.69",
   "chantVersion": ">=0.1.0",
   "namespace": "Fly"
 }

package/dist/okf/index.md

@@ -17,5 +17,5 @@ okf_version: '0.2'
 * [FLY002](/rules/FLY002.md) - Sane guest sizing
 * [FLY004](/rules/FLY004.md) - No secret literals in machine config
 * [FLY010](/rules/FLY010.md) - Machine config must specify an image — a Machine cannot boot without one
-* [FLY011](/rules/FLY011.md) - A machine mount's volume must resolve to a Volume declared in the stack
+* [FLY011](/rules/FLY011.md) - A machine mount's volume must resolve to a Volume declared in the stack, or be a volume id (vol_...)
 * [FLY012](/rules/FLY012.md) - Machine schedule must be hourly, daily, weekly or monthly

package/dist/okf/rules/FLY011.md

@@ -1,14 +1,14 @@
 ---
 type: post-synth-check
 title: FLY011
-description: A machine mount's volume must resolve to a Volume declared in the stack
+description: A machine mount's volume must resolve to a Volume declared in the stack, or be a volume id (vol_...)
 id: FLY011
 severity: error
 category: post-synth
 lexicon: fly
 docs: https://intentius.io/chant/lexicons/fly/rules/
 ---
-A machine mount's volume must resolve to a Volume declared in the stack
+A machine mount's volume must resolve to a Volume declared in the stack, or be a volume id (vol_...)
 
 ## Applies to
 

package/dist/okf/types/Machine.md

@@ -22,5 +22,5 @@ resource_type: Fly::Machines::Machine
 ## Governed by
 
 - [FLY010](/rules/FLY010.md): Machine config must specify an image — a Machine cannot boot without one
-- [FLY011](/rules/FLY011.md): A machine mount's volume must resolve to a Volume declared in the stack
+- [FLY011](/rules/FLY011.md): A machine mount's volume must resolve to a Volume declared in the stack, or be a volume id (vol_...)
 - [FLY012](/rules/FLY012.md): Machine schedule must be hourly, daily, weekly or monthly

package/dist/okf/types/Volume.md

@@ -26,4 +26,4 @@ resource_type: Fly::Machines::Volume
 
 ## Governed by
 
-- [FLY011](/rules/FLY011.md): A machine mount's volume must resolve to a Volume declared in the stack
+- [FLY011](/rules/FLY011.md): A machine mount's volume must resolve to a Volume declared in the stack, or be a volume id (vol_...)

package/dist/op/activities/fly-apply.d.ts

@@ -21,6 +21,7 @@
  * `FLY_FLAPS_BASE_URL` (or an explicit `endpoint` arg), so the same code points
  * at real Fly or at mudflaps (`:4280`).
  */
+export { isVolumeId } from "../../volume-id.js";
 import { type ApplyResult } from "@intentius/chant/apply";
 /** Default flaps host when neither an `endpoint` arg nor `FLY_FLAPS_BASE_URL` is set. */
 export declare const DEFAULT_FLAPS_BASE_URL = "https://api.machines.dev";
@@ -52,9 +53,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;
 }
 /**
  * Resolve the flaps base URL (D3): an explicit `endpoint` arg wins, then the
@@ -214,11 +240,18 @@ export declare function listMachines(ctx: ApplyCtx, app: string, http: FlyHttp,
  *
  * 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 declare function applyMachine(ctx: ApplyCtx, app: string, entityName: string, req: FlapsRequest, http: FlyHttp, signal?: AbortSignal, opts?: WaitOpts): Promise<{
+export declare function applyMachine(ctx: ApplyCtx, app: string, entityName: string, req: FlapsRequest, http: FlyHttp, signal?: AbortSignal, opts?: WaitOpts & {
+    volumeAliases?: ReadonlyMap<string, string>;
+}): Promise<{
     action: "created" | "updated" | "noop";
     id: string;
     name: string;
+    updatedAt?: string;
 }>;
 /** How {@link destroyMachine} treats a machine that is still running. */
 export interface DestroyOpts extends WaitOpts {
@@ -266,6 +299,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. */
 export interface FlapsIp {
@@ -291,6 +327,53 @@ export declare function ipType(shared: boolean | undefined, address: string): st
 export declare function declaredIpType(type: unknown): string;
 /** List an app's live volumes (flaps returns a bare array). */
 export declare function listVolumes(ctx: ApplyCtx, app: string, http: FlyHttp, signal?: AbortSignal): Promise<FlapsVolume[]>;
+/** 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 declare function volumeAliases(plan: FlyPlan): Map<string, string>;
+/** True when a config has a mount that names its volume rather than giving its id. Pure. */
+export declare function mountsNeedResolving(config: unknown): boolean;
+/**
+ * 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 declare function pickVolume(app: string, name: string, volumes: FlapsVolume[], target: MountTarget): FlapsVolume;
+/**
+ * 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 declare function resolveMountsWith<T>(app: string, config: T, volumes: FlapsVolume[], target: MountTarget, aliases?: ReadonlyMap<string, string>): 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 declare function resolveMounts<T>(ctx: ApplyCtx, app: string, config: T, target: MountTarget, http: FlyHttp, signal?: AbortSignal, aliases?: ReadonlyMap<string, string>): Promise<T>;
+/**
+ * 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 declare function alignMountsWithLive<T>(declared: T, live: unknown, aliases?: ReadonlyMap<string, string>): T;
 /** List an app's live IP assignments (`{ ips: [...] }`). */
 export declare function listIps(ctx: ApplyCtx, app: string, http: FlyHttp, signal?: AbortSignal): Promise<FlapsIp[]>;
 /**
@@ -411,6 +494,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>;
 }
 export declare function toApplyResult(result: {
     apps: Array<{