@intentius/chant-lexicon-fly 0.124.63 → 0.124.65

package/src/lint/post-synth/fly012-machine-schedule.ts

@@ -0,0 +1,39 @@
+/**
+ * FLY012: a Machine's `schedule` is one the Machines API runs (#4696).
+ *
+ * Fly runs a scheduled Machine `hourly`, `daily`, `weekly` or `monthly`, and
+ * rejects anything else when the Machine is created or updated. A cron
+ * expression is the usual mistake, so name the four values at build time
+ * rather than at the first release.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readProps, entityTypeOf } from "./fly-helpers";
+
+const SCHEDULES = ["hourly", "daily", "weekly", "monthly"];
+
+export const fly012: PostSynthCheck = {
+  id: "FLY012",
+  description: "Machine schedule must be hourly, daily, weekly or monthly",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const [name, entity] of ctx.entities) {
+      if (entityTypeOf(entity) !== "Fly::Machines::Machine") continue;
+      const config = readProps(entity).config;
+      if (!config) continue;
+      const schedule = readProps(config).schedule;
+      if (schedule === undefined) continue;
+      if (typeof schedule !== "string" || !SCHEDULES.includes(schedule)) {
+        diagnostics.push({
+          checkId: "FLY012",
+          severity: "error",
+          message: `Machine "${name}" has schedule ${JSON.stringify(schedule)}; Fly runs a Machine ${SCHEDULES.join(", ")}`,
+          entity: name,
+          lexicon: "fly",
+        });
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/index.ts

@@ -2,8 +2,10 @@
 import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
 import { fly010 } from "./fly010-machine-requires-image";
 import { fly011 } from "./fly011-mount-references-declared-volume";
+import { fly012 } from "./fly012-machine-schedule";
 
 export const postSynthChecks: PostSynthCheck[] = [
   fly010,
   fly011,
+  fly012,
 ];

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

@@ -37,6 +37,8 @@ import {
   acquireLease,
   withLease,
   waitForMachine,
+  skipsLaunch,
+  machineSchedule,
   flyApply,
   flyDelete,
   toApplyResult,
@@ -655,6 +657,88 @@ describe("flyApply creates certificates at /certificates/acme (#3114)", () => {
   });
 });
 
+/**
+ * #4696: a scheduled Machine is stopped between runs. The applier creates and
+ * updates it with `skip_launch`, so Fly doesn't start it, and waits for it to
+ * rest unstarted instead of waiting for `started`.
+ */
+describe("a scheduled Machine is applied without starting it (#4696)", () => {
+  const app = { endpoint: "/v1/apps", method: "POST", body: { app_name: "demo" } };
+  const dump = (image: string, extra: Record<string, unknown> = {}) => ({
+    endpoint: "/v1/apps/demo/machines",
+    method: "POST",
+    body: { name: "dump", config: { image, schedule: "hourly", metadata: { ...OWNED_META } }, ...extra },
+  });
+  const run = (fake: ReturnType<typeof createMachinesFake>, entries: Record<string, unknown>, prune = false) =>
+    flyApply({ plan: entries as never, endpoint: CTX.base, wait: NO_WAIT, prune }, undefined, fake.http);
+  /** The bodies of the machine creates and updates the fake saw. */
+  function recording() {
+    const fake = createMachinesFake();
+    const bodies: Array<Record<string, unknown>> = [];
+    const http: FlyHttp = (method, url, body, headers, signal) => {
+      if (method === "POST" && /\/machines(\/[^/]+)?$/.test(new URL(url).pathname)) bodies.push(body as Record<string, unknown>);
+      return fake.http(method, url, body, headers, signal);
+    };
+    return { fake: { ...fake, http }, raw: fake, bodies };
+  }
+
+  test("which Machines skip launch: a schedule, unless skip_launch says otherwise", () => {
+    expect(skipsLaunch({ config: { image: "x" } })).toBe(false);
+    expect(skipsLaunch({ config: { image: "x", schedule: "daily" } })).toBe(true);
+    expect(skipsLaunch({ config: { image: "x", schedule: "daily" }, skip_launch: false })).toBe(false);
+    expect(skipsLaunch({ config: { image: "x" }, skip_launch: true })).toBe(true);
+    expect(machineSchedule({ schedule: "hourly" })).toBe("hourly");
+    expect(machineSchedule({ schedule: "" })).toBeUndefined();
+  });
+
+  test("created with skip_launch and left created; updated with skip_launch and left stopped; a re-apply is a no-op", async () => {
+    const { fake, raw, bodies } = recording();
+    const first = await run(fake, { app, dump: dump("dump:1") });
+    expect(first.machines).toEqual([{ app: "demo", name: "dump", action: "created" }]);
+    expect(bodies[0]).toMatchObject({ name: "dump", skip_launch: true });
+    expect(raw.machine("demo", "dump")!.state).toBe("created");
+    expect(raw.calls.some((c) => c.endsWith("/wait"))).toBe(false);
+
+    raw.machine("demo", "dump")!.state = "stopped"; // it ran once, on its schedule
+    const second = await run(fake, { app, dump: dump("dump:2") });
+    expect(second.machines).toEqual([{ app: "demo", name: "dump", action: "updated" }]);
+    expect(bodies[1]).toMatchObject({ skip_launch: true });
+    expect(raw.machine("demo", "dump")).toMatchObject({ state: "stopped", config: { image: "dump:2", schedule: "hourly" } });
+
+    const third = await run(fake, { app, dump: dump("dump:2") });
+    expect(third.machines[0].action).toBe("noop");
+    expect(bodies).toHaveLength(2);
+  });
+
+  test("skip_launch: false starts a scheduled Machine, as a plain create does", async () => {
+    const { fake, raw, bodies } = recording();
+    await run(fake, { app, dump: dump("dump:1", { skip_launch: false }) });
+    expect(bodies[0].skip_launch).toBe(false);
+    expect(raw.machine("demo", "dump")!.state).toBe("started");
+  });
+
+  test("a Machine that never rests unstarted fails the apply at the deadline, naming its state", async () => {
+    // A flaps that starts every Machine, skip_launch or not.
+    const fake = createMachinesFake();
+    const http: FlyHttp = async (method, url, body, headers, signal) => {
+      const out = await fake.http(method, url, body, headers, signal);
+      for (const m of fake.machines.get("demo") ?? []) m.state = "started";
+      return out;
+    };
+    await expect(
+      flyApply({ plan: { app, dump: dump("dump:1") } as never, endpoint: CTX.base, wait: { intervalMs: 0, deadlineMs: 50 } }, undefined, http),
+    ).rejects.toThrow(/did not settle unstarted .*last started/);
+  });
+
+  test("prune keeps a declared scheduled Machine", async () => {
+    const fake = createMachinesFake();
+    await run(fake, { app, dump: dump("dump:1") });
+    const out = await run(fake, { app, dump: dump("dump:1") }, true);
+    expect(out.pruned).toEqual([]);
+    expect(fake.machine("demo", "dump")).toBeDefined();
+  });
+});
+
 /**
  * #3224: Fly pages the certificate list (25 by default, 500 at most, with a
  * `next_cursor`), and the in-memory flaps does the same. Every reader goes

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

@@ -426,6 +426,65 @@ export async function waitForMachine(
   throw new Error(`machine ${app}/${id} did not reach ${state} within the deadline`);
 }
 
+// ── Scheduled Machines (#4696) ──────────────────────────────────────────────────
+
+/**
+ * The Machines API's `schedule` values: Fly runs the Machine once per
+ * interval, counted from when the Machine was created or last updated.
+ */
+export const MACHINE_SCHEDULES = ["hourly", "daily", "weekly", "monthly"] as const;
+
+/** A Machine config's `schedule`, or undefined when it runs no schedule. Pure. */
+export function machineSchedule(config: unknown): string | undefined {
+  const schedule = (config as { schedule?: unknown } | undefined)?.schedule;
+  return typeof schedule === "string" && schedule ? schedule : undefined;
+}
+
+/**
+ * True when creating or updating the Machine leaves it unstarted: its
+ * request sets `skip_launch: true`, or its config has a `schedule` and the
+ * request doesn't set `skip_launch: false`. A scheduled Machine is stopped
+ * between runs, so an apply moves it to its new config and leaves the next
+ * run to Fly. Pure.
+ */
+export function skipsLaunch(body: Record<string, unknown>): boolean {
+  if (typeof body.skip_launch === "boolean") return body.skip_launch;
+  return machineSchedule(body.config) !== undefined;
+}
+
+/** The states a Machine rests in when nothing started it. */
+const UNLAUNCHED_STATES = new Set(["created", "stopped", "suspended"]);
+
+/**
+ * Poll the Machine until it rests unstarted (`created`, `stopped` or
+ * `suspended`) at `version` (its new `instance_id`, when known): what a
+ * create or update with `skip_launch` settles in. flaps' `/wait` can't wait
+ * for this, since a Machine created without launching stays `created`.
+ */
+export async function waitForUnlaunched(
+  ctx: ApplyCtx,
+  app: string,
+  id: string,
+  version: string,
+  http: FlyHttp,
+  signal?: AbortSignal,
+  opts: WaitOpts = {},
+): Promise<string> {
+  const interval = opts.intervalMs ?? 1_000;
+  const deadline = Date.now() + (opts.deadlineMs ?? 300_000);
+  let seen = "";
+  while (Date.now() < deadline) {
+    if (signal?.aborted) throw new Error("waitForUnlaunched aborted");
+    const res = await http("GET", machineUrl(ctx.base, app, id), undefined, undefined, signal);
+    if (res.status >= 300) throw new Error(`machine ${app}/${id} lookup failed (${res.status}): ${res.text}`);
+    const m = parseMachine(res.text);
+    seen = m.state;
+    if (UNLAUNCHED_STATES.has(m.state) && (!version || m.instance_id === version)) return m.state;
+    await sleep(interval, signal);
+  }
+  throw new Error(`machine ${app}/${id} did not settle unstarted within the deadline (last ${seen || "unknown"})`);
+}
+
 // ── Resource operations ────────────────────────────────────────────────────────
 
 /** Create the app if absent (idempotent). A create-time conflict means it exists. */
@@ -466,6 +525,9 @@ export async function listMachines(
  * machine's new `instance_id`. Updates go through a lease. The declared machine
  * is identified by name (falling back to the plan entity name), so re-applying
  * an unchanged machine is a no-op.
+ *
+ * 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.
  */
 export async function applyMachine(
   ctx: ApplyCtx,
@@ -477,8 +539,13 @@ export async function applyMachine(
   opts: WaitOpts = {},
 ): Promise<{ action: "created" | "updated" | "noop"; id: string; name: string }> {
   const name = typeof req.body.name === "string" && req.body.name ? req.body.name : entityName;
-  const body = { ...req.body, name };
+  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)
+      : waitForMachine(ctx, app, m.id, m.instance_id, http, signal, opts);
 
   const live = (await listMachines(ctx, app, http, signal)).find((m) => m.name === name);
 
@@ -486,7 +553,7 @@ export async function applyMachine(
     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 waitForMachine(ctx, app, m.id, m.instance_id, http, signal, opts);
+    await settle(m);
     return { action: "created", id: m.id, name };
   }
 
@@ -499,7 +566,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 waitForMachine(ctx, app, m.id, m.instance_id, http, signal, opts);
+  await settle(m);
   return { action: "updated", id: m.id, name };
 }
 

package/src/op/activities/machine-release.ts

@@ -16,7 +16,10 @@
  *
  * - {@link flyMachineRelease}: upload and start. Apply the declared plan with
  *   the Machine serving the release (its image or env overridden when the
- *   release says so), and report the release and config it replaced.
+ *   release says so), and report the release and config it replaced. A
+ *   scheduled Machine (`config.schedule`, #4696) is updated without starting:
+ *   it runs on its schedule. The plan's other Machines can take images of
+ *   their own (`images`).
  * - {@link flyMachineExec}: run a command inside the Machine (a migration).
  * - {@link flyMachineRestart}, {@link flyMachineStop}: under a lease, then
  *   wait for the Machine to settle.
@@ -40,7 +43,9 @@ import {
   machineAppSegment,
   resolveApp,
   resolveEndpoint,
+  skipsLaunch,
   waitForMachine,
+  waitForUnlaunched,
   withLease,
   LEASE_NONCE_HEADER,
   type ApplyCtx,
@@ -67,20 +72,26 @@ export interface ReleaseTarget {
   request: FlapsRequest;
 }
 
-/**
- * The Machine a release targets: the plan's one Machine, or the one `machine`
- * names (an entity name or a Machine name). Pure.
- */
-export function releaseTarget(plan: FlyPlan, machine?: string): ReleaseTarget {
+/** Every Machine the plan declares, with its App resolved. Pure. */
+export function planMachines(plan: FlyPlan): ReleaseTarget[] {
   const appNames = Object.values(plan).filter(isAppRequest).map(appNameFromRequest);
   const soleApp = appNames.length === 1 ? appNames[0] : undefined;
-  const machines = Object.entries(plan)
+  return Object.entries(plan)
     .filter(([, req]) => isMachineRequest(req))
     .map(([entity, request]) => ({
+      app: resolveApp(machineAppSegment(request.endpoint), soleApp),
       entity,
       request,
       name: typeof request.body.name === "string" && request.body.name ? request.body.name : entity,
     }));
+}
+
+/**
+ * The Machine a release targets: the plan's one Machine, or the one `machine`
+ * names (an entity name or a Machine name). Pure.
+ */
+export function releaseTarget(plan: FlyPlan, machine?: string): ReleaseTarget {
+  const machines = planMachines(plan);
   const picked = machine ? machines.filter((m) => m.entity === machine || m.name === machine) : machines;
   if (picked.length !== 1) {
     throw new Error(
@@ -89,8 +100,7 @@ export function releaseTarget(plan: FlyPlan, machine?: string): ReleaseTarget {
         : `the fly plan declares ${machines.length} Machines (${machines.map((m) => m.entity).join(", ")}): name the one that serves the release`,
     );
   }
-  const [m] = picked;
-  return { app: resolveApp(machineAppSegment(m.request.endpoint), soleApp), entity: m.entity, name: m.name, request: m.request };
+  return picked[0];
 }
 
 const TERMINAL = new Set(["destroyed", "destroying"]);
@@ -147,6 +157,12 @@ export interface FlyMachineReleaseArgs extends FlapsTarget {
   files?: MachineFile[];
   /** The command the Machine starts, in place of the image's: an argv, or a string run with `sh -c`. */
   cmd?: string[] | string;
+  /**
+   * Images for the plan's other Machines, by entity or Machine name (#4696):
+   * a scheduled Machine beside the one that serves, say, built from the same
+   * commit. A name that is no other Machine in the plan is refused.
+   */
+  images?: Record<string, string>;
   wait?: WaitOpts;
 }
 
@@ -170,6 +186,13 @@ export interface FlyMachineReleaseResult {
   config: MachineConfig;
   /** What the Machine served before, when it existed: its release (if it named one) and its config. */
   previous: { release?: MachineRelease; config: MachineConfig } | null;
+  /** True when the Machine was left unstarted: a scheduled Machine, which runs on its schedule (#4696). */
+  unlaunched: boolean;
+  /**
+   * The plan's other Machines: what the apply did to each, whether it was
+   * left unstarted, and the config it had before (null when it was created).
+   */
+  others: Array<{ name: string; app: string; action: "created" | "updated" | "noop"; unlaunched: boolean; previous: MachineConfig | null }>;
 }
 
 /**
@@ -178,6 +201,11 @@ export interface FlyMachineReleaseResult {
  * under a lease, so the release serves from here on. A Machine that already
  * serves this release keeps the `previousDigest` it shipped with, so running a
  * release twice never makes it its own predecessor.
+ *
+ * A scheduled Machine (its config has a `schedule`, #4696), the target or
+ * another in the plan, is created or updated with `skip_launch` and left
+ * unstarted: Fly starts it on its schedule. Fly counts the interval from the
+ * update, so each release pushes the next run back by up to one interval.
  */
 export async function flyMachineRelease(
   args: FlyMachineReleaseArgs,
@@ -211,20 +239,53 @@ export async function flyMachineRelease(
     release,
   );
   const request: FlapsRequest = { ...target.request, body: { ...target.request.body, config } };
+
+  // The plan's other Machines, each with its own image when `images` names it.
+  const others = planMachines(plan).filter((m) => m.entity !== target.entity);
+  const images = { ...(args.images ?? {}) };
+  const overrides: FlyPlan = {};
+  for (const m of others) {
+    const image = images[m.entity] ?? images[m.name];
+    delete images[m.entity];
+    delete images[m.name];
+    if (image === undefined) continue;
+    const declaredOther = (m.request.body.config ?? {}) as MachineConfig;
+    overrides[m.entity] = { ...m.request, body: { ...m.request.body, config: { ...declaredOther, image } } };
+  }
+  const unknown = Object.keys(images);
+  if (unknown.length > 0) {
+    throw new Error(
+      `images names ${unknown.map((n) => `"${n}"`).join(", ")}, which the fly plan declares as no Machine other than the one that serves (others: ${others.map((m) => m.entity).join(", ") || "none"}); the serving Machine's image is \`image\``,
+    );
+  }
+  const before = new Map<string, MachineConfig | null>();
+  for (const m of others) {
+    const found = await findMachine(ctx, m.app, m.name, http, signal).catch(() => undefined);
+    before.set(m.entity, found ? ((found.config as MachineConfig | undefined) ?? {}) : null);
+  }
+
   const applied = await flyApply(
-    { plan: { ...plan, [target.entity]: request }, endpoint: args.endpoint, token: args.token, wait: args.wait },
+    { plan: { ...plan, ...overrides, [target.entity]: request }, endpoint: args.endpoint, token: args.token, wait: args.wait },
     signal,
     http,
   );
-  const action = applied.machines.find((m) => m.app === target.app && m.name === target.name)?.action ?? "noop";
+  const actionOf = (app: string, name: string) => applied.machines.find((m) => m.app === app && m.name === name)?.action ?? "noop";
   const now = await mustFindMachine(ctx, target.app, target.name, http, signal);
   return {
     app: target.app,
     machine: { id: now.id, name: target.name },
-    action,
+    action: actionOf(target.app, target.name),
     release,
     config,
     previous: live ? { ...(liveRelease ? { release: liveRelease } : {}), config: liveConfig ?? {} } : null,
+    unlaunched: skipsLaunch(request.body),
+    others: others.map((m) => ({
+      name: m.name,
+      app: m.app,
+      action: actionOf(m.app, m.name),
+      unlaunched: skipsLaunch((overrides[m.entity] ?? m.request).body),
+      previous: before.get(m.entity) ?? null,
+    })),
   };
 }
 
@@ -343,8 +404,9 @@ export interface FlyMachineVerifyArgs extends FlapsTarget {
 }
 
 /**
- * The Machine is started and its metadata names release `digest`. Given a
- * `url`, its health endpoint answers 2xx too, and when that answer is JSON
+ * The Machine is started and its metadata names release `digest`. A scheduled
+ * Machine (#4696) may also be resting unstarted (`created`, `stopped` or
+ * `suspended`) between runs. Given a `url`, its health endpoint answers 2xx too, and when that answer is JSON
  * naming a `revision` or `digest`, it is this release's (the commit or the
  * digest). Retries until `timeoutMs`, then throws the last reason.
  */
@@ -362,7 +424,9 @@ export async function flyMachineVerify(
     if (signal?.aborted) throw new Error("flyMachineVerify aborted");
     try {
       const m = await mustFindMachine(ctx, args.app, args.machine, http, signal);
-      if (m.state !== "started") throw new Error(`machine ${args.app}/${m.id} is ${m.state}`);
+      const scheduled = skipsLaunch({ config: m.config });
+      const resting = scheduled && ["created", "stopped", "suspended"].includes(m.state);
+      if (m.state !== "started" && !resting) throw new Error(`machine ${args.app}/${m.id} is ${m.state}`);
       const release = readMachineRelease(m.config?.metadata);
       if (release?.digest !== args.digest) {
         throw new Error(`machine ${args.app}/${m.id} serves ${release?.digest ?? "no release"}, expected ${args.digest}`);
@@ -405,6 +469,8 @@ export interface FlyMachineRestoreArgs extends FlapsTarget {
  * Put a recorded Machine config back: update the Machine to exactly `config`
  * under a lease and wait for it to be started. Used on a failed release (the
  * config it replaced) and by a rollback (the config an earlier release applied).
+ * A scheduled config (#4696) goes back with `skip_launch`, and the wait is for
+ * the Machine to rest unstarted.
  */
 export async function flyMachineRestore(
   args: FlyMachineRestoreArgs,
@@ -413,8 +479,10 @@ export async function flyMachineRestore(
 ): Promise<{ id: string; release?: MachineRelease }> {
   const ctx: ApplyCtx = { base: resolveEndpoint(args) };
   const m = await mustFindMachine(ctx, args.app, args.machine, http, signal);
+  const unlaunched = skipsLaunch({ config: args.config });
+  const body = { name: m.name, config: args.config, ...(unlaunched ? { skip_launch: true } : {}) };
   const res = await withLease(ctx, args.app, m.id, http, signal, (nonce) =>
-    http("POST", machinePath(ctx, args.app, m.id), { name: m.name, config: args.config }, { [LEASE_NONCE_HEADER]: nonce }, signal),
+    http("POST", machinePath(ctx, args.app, m.id), body, { [LEASE_NONCE_HEADER]: nonce }, signal),
   );
   if (res.status >= 300) throw new Error(`restore of machine ${args.app}/${m.id} failed (${res.status}): ${res.text}`);
   let instance = "";
@@ -423,7 +491,8 @@ export async function flyMachineRestore(
   } catch {
     instance = "";
   }
-  await waitForMachine(ctx, args.app, m.id, instance, http, signal, args.wait ?? {});
+  if (unlaunched) await waitForUnlaunched(ctx, args.app, m.id, instance, http, signal, args.wait ?? {});
+  else await waitForMachine(ctx, args.app, m.id, instance, http, signal, args.wait ?? {});
   const release = readMachineRelease(args.config.metadata);
   return { id: m.id, ...(release ? { release } : {}) };
 }

package/src/op/activities/machines-fake.ts

@@ -125,7 +125,8 @@ export function createMachinesFake(options: MachinesFakeOptions = {}): MachinesF
             instance_id: nextId("I"),
             config: structuredClone((b.config ?? {}) as FakeMachine["config"]),
           };
-          m.state = settle(m);
+          // skip_launch: the Machine is created and not booted (#4696).
+          m.state = b.skip_launch === true ? "created" : settle(m);
           machines.set(app, [...list(app), m]);
           return json(200, m);
         }
@@ -137,7 +138,9 @@ export function createMachinesFake(options: MachinesFakeOptions = {}): MachinesF
         if (method === "POST") {
           m.config = structuredClone((b.config ?? {}) as FakeMachine["config"]);
           m.instance_id = nextId("I");
-          m.state = settle(m);
+          // skip_launch: the new config isn't started (#4696). A Machine that
+          // never ran stays created; one that ran is stopped.
+          m.state = b.skip_launch === true ? (m.state === "created" ? "created" : "stopped") : settle(m);
           return json(200, m);
         }
         if (method === "DELETE") {

package/src/skills/chant-fly-ops.md

@@ -31,6 +31,8 @@ If a machine never reaches `started`:
 | Wait fails with a non-408 status | flaps rejected the machine (bad config the build check did not catch, or an org-side limit) | Read the error body; fix the config and re-apply |
 | Wait times out at the deadline | The machine cannot reach `started` in time | Inspect the machine directly on the org, then re-apply once the cause is fixed |
 
+A scheduled machine is the exception: it isn't started, so the applier polls the machine until it rests `created` or `stopped` at its new config instead (see "A scheduled Machine" below).
+
 ## Lease conflicts
 
 Mutating an existing machine (update or destroy) is gated behind a Machines API lease. `flyApply` acquires a lease, echoes the nonce in the `fly-machine-lease-nonce` header on the mutation, and releases the lease afterward. A leaked lease expires on its own TTL, so release is best-effort.
@@ -161,3 +163,48 @@ export default Op({
 ```
 
 A rollback's own ledger record is not counted as a release, so running the Op again plans the same rollback, leaves the Machine as it is and records nothing. `to: "sha256:..."` on `releaseRollbackPlan` picks another release. Migrations are not undone.
+
+### A scheduled Machine
+
+A Machine with a `schedule` in its config runs once an hour, day, week or month (`hourly`, `daily`, `weekly`, `monthly`; FLY012 refuses anything else, a cron expression included) and is stopped between runs. A backup or a dump is the usual case. Declare it beside the Machine that serves, with no process group of its own:
+
+```ts
+import { App, Machine, MachineConfig } from "@intentius/chant-lexicon-fly";
+
+export const platform = new App({ name: "platform", org_slug: "acme" });
+
+export const web = new Machine({
+  name: "web",
+  region: "iad",
+  config: new MachineConfig({ image: "registry.fly.io/platform:declared" }),
+});
+
+export const dump = new Machine({
+  name: "platform-dump",
+  region: "iad",
+  config: new MachineConfig({
+    image: "registry.fly.io/platform:dump-declared",
+    schedule: "hourly",
+    metadata: { role: "platform-dump" },
+  }),
+});
+```
+
+`flyApply` creates and updates a scheduled Machine with `skip_launch: true`, so an apply or a release moves it to its new config and image and never starts it. The next run is Fly's. Set `skip_launch: false` on the Machine to have each apply start it as well. Fly counts the interval from the Machine's last update, so each apply that changes it pushes the next run back by up to one interval: under `daily`, releases less than a day apart can keep it from ever running. `hourly`, with the job skipping a run when its last output is recent enough, keeps a daily job daily.
+
+`fly-release` releases the Machine named by `machine` and applies the rest of the plan with it. `images` gives the plan's other Machines images of their own, by entity or Machine name; a name that is no other Machine in the plan is refused before anything changes:
+
+```ts
+{
+  kind: "fly-release",
+  plan: "dist/fly.json",
+  machine: "web",
+  digest: "@Publish.digest",
+  image: "@Publish.uri",
+  images: { dump: "@PublishDump.uri" },
+}
+```
+
+The serving Machine is started and verified as usual. The scheduled one is updated and left stopped. If the release fails after the Machines changed, the serving Machine goes back to what it served and the scheduled Machine goes back to its old config, still stopped. Only the serving Machine's configs are recorded, so `fly-rollback` and the step's saga rollback put back the serving Machine alone.
+
+A scheduled Machine can be the one released, too (`machine: "platform-dump"`, or the plan's only Machine). It's updated and left stopped, its metadata names the release, and verify accepts it stopped, or started in the middle of a run, as long as it names this release. Such a release takes no `migrations` and no `verify.url`, since nothing runs in the Machine between runs to exec into or answer a health check; either is refused before the Machine changes. A restore or rollback puts its old config back without starting it.

package/src/skills/chant-fly.md

@@ -73,6 +73,7 @@ Build synthesizes the flaps plan and runs the lint rules before anything reaches
 | FLY004 | A secret value written inline in machine config |
 | FLY010 | A machine config with no `image` |
 | FLY011 | A machine mount that references a `Volume` not declared in the stack (checked across files) |
+| FLY012 | A machine `schedule` other than `hourly`, `daily`, `weekly` or `monthly` |
 
 Fix every reported violation before applying. Secret values belong in a `Secret` or a reference, never inline (FLY004).
 
@@ -81,6 +82,7 @@ Fix every reported violation before applying. Secret values belong in a `Secret`
 `flyApply` reads the serialized plan and applies it to flaps in dependency order: app, then volumes, then machines, then IPs, certificates, and secrets. Per machine it does a GET-then-create or update, then waits.
 
 - Create or update: POST the machine, then poll `GET .../wait` until it reaches `started` at its new `instance_id`. flaps caps its own long-poll at 60 seconds and answers 408 on expiry, so the client re-polls until its deadline (default 300 seconds).
+- A scheduled machine (`config.schedule`) is created and updated with `skip_launch: true`, and the wait is for it to rest unstarted (`created` or `stopped`) at its new `instance_id`. Fly starts it on its schedule. `skip_launch: false` on the Machine starts it like any other.
 - No-op on no drift: a re-apply of an unchanged machine (config structurally equal to live) does nothing.
 - Leases: mutating an existing machine goes through the Machines API lease protocol. `flyApply` acquires a lease, echoes the nonce in the `fly-machine-lease-nonce` header on the mutation, and re-acquires and retries once if the lease was lost. Concurrent operators stay out of each other's way.
 
@@ -112,7 +114,7 @@ export default flyDeploy({ app: "local-fly-demo" });
 
 | Command | Description |
 |---------|-------------|
-| `chant build src/` | Synthesize the flaps plan and run lint (FLY001/FLY002/FLY004/FLY010/FLY011) |
+| `chant build src/` | Synthesize the flaps plan and run lint (FLY001/FLY002/FLY004/FLY010/FLY011/FLY012) |
 | `chant run fly` | Run the deploy Op (boot, build, apply, verify, teardown) |
 | `FLY_FLAPS_BASE_URL=...` | Point the same code at mudflaps or a real Fly org |
 | `FLY_API_TOKEN=...` | Bearer token for a real Fly org (mudflaps ignores it) |