@intentius/chant-lexicon-fly 0.90.0 → 0.93.0

package/src/op/activities/sprites.test.ts

@@ -214,6 +214,26 @@ describe("spriteExecWsUrl", () => {
   test("https → wss", () => {
     expect(spriteExecWsUrl("https://api.sprites.dev", "s", "ls").startsWith("wss://api.sprites.dev/")).toBe(true);
   });
+
+  test("dir → a single dir param (#2765)", () => {
+    const url = new URL(spriteExecWsUrl("http://x", "task-1", "pwd", { dir: "/work" }));
+    expect(url.searchParams.get("dir")).toBe("/work");
+  });
+
+  test("no dir → no dir param (#2765)", () => {
+    const url = new URL(spriteExecWsUrl("http://x", "task-1", "pwd"));
+    expect(url.searchParams.has("dir")).toBe(false);
+  });
+
+  test("env → repeated KEY=VALUE params, matching wisp's optsFromValues (#2765)", () => {
+    const url = new URL(spriteExecWsUrl("http://x", "task-1", "env", { env: { FOO: "1", BAR: "two" } }));
+    expect(url.searchParams.getAll("env")).toEqual(["FOO=1", "BAR=two"]);
+  });
+
+  test("no env → no env params (#2765)", () => {
+    const url = new URL(spriteExecWsUrl("http://x", "task-1", "echo hi"));
+    expect(url.searchParams.has("env")).toBe(false);
+  });
 });
 
 // ── Activity request shapes (injected SpritesHttp; no real sockets) ───────────

package/src/op/activities/sprites.ts

@@ -179,10 +179,19 @@ export function splitCommand(cmd: string): string[] {
 }
 
 /**
- * Build the `wss://.../exec?cmd=...&path=...&stdin=false&cc=true` URL for a
- * command (http→ws, https→wss). Pure.
+ * Build the `wss://.../exec?cmd=...&path=...&stdin=false&cc=true[&dir=...][&env=K=V]*`
+ * URL for a command (http→ws, https→wss). `dir` and `env` (#2765) are sent the
+ * way wisp's and spritzer's real exec API take them: `dir` is a single query
+ * param, and each `env` entry is its own repeated `env=KEY=VALUE` param — see
+ * wisp's `optsFromValues` (`Dir: q.Get("dir")`, `Env: q["env"]`) and spritzer's
+ * container-mode wrapping (`--dir`/`--env` per `real.go`). Pure.
  */
-export function spriteExecWsUrl(base: string, id: string, cmd: string): string {
+export function spriteExecWsUrl(
+  base: string,
+  id: string,
+  cmd: string,
+  opts: { env?: Record<string, string>; dir?: string } = {},
+): string {
   const wsBase = base.replace(/^http(s?):\/\//i, (_m, s: string) => `ws${s}://`);
   const argv = splitCommand(cmd);
   const params = new URLSearchParams();
@@ -190,6 +199,10 @@ export function spriteExecWsUrl(base: string, id: string, cmd: string): string {
   params.set("path", argv[0] ?? "");
   params.set("stdin", "false");
   params.set("cc", "true");
+  if (opts.dir) params.set("dir", opts.dir);
+  if (opts.env) {
+    for (const [k, v] of Object.entries(opts.env)) params.append("env", `${k}=${v}`);
+  }
   return `${wsBase}/v1/sprites/${encodeURIComponent(id)}/exec?${params.toString()}`;
 }
 
@@ -281,8 +294,16 @@ export interface SpriteExecArgs {
   id: string;
   /** Command to run inside the sprite (tokenized into argv, quotes respected). */
   cmd: string;
-  /** Per-exec timeout in ms. */
+  /**
+   * Per-exec timeout in ms (#2765). When it elapses before the command exits,
+   * the exec WebSocket is aborted and the activity throws a timeout error —
+   * previously declared and never enforced.
+   */
   timeoutMs?: number;
+  /** Extra environment variables for the command, on top of the sprite's own (#2765). */
+  env?: Record<string, string>;
+  /** Working directory to run the command in (#2765). */
+  dir?: string;
   endpoint?: string;
   token?: string;
 }
@@ -405,15 +426,20 @@ export async function spriteCreate(
 
 /**
  * Run a command in the sprite over the control WebSocket (non-PTY stream
- * framing, per superfly/sprites-go). Connects to `wss://.../exec`, sends a
- * single `[4]` (stdin EOF), accumulates stdout/stderr frames, and reads the
- * exit code from the `[3]` frame. A non-zero exit is a failed activity (it
- * throws) so a risky step fails its phase and triggers `onFailure`
- * compensation (S5).
+ * framing, per superfly/sprites-go). Connects to `wss://.../exec` (`dir`/`env`
+ * riding on the URL — #2765), sends a single `[4]` (stdin EOF), accumulates
+ * stdout/stderr frames, and reads the exit code from the `[3]` frame. A
+ * non-zero exit is a failed activity (it throws) so a risky step fails its
+ * phase and triggers `onFailure` compensation (S5).
+ *
+ * `timeoutMs` (#2765) bounds the whole exec: a timer set at connect time
+ * terminates the WebSocket and rejects with a timeout error once it elapses
+ * without the command finishing. Previously declared on `SpriteExecArgs` and
+ * never read.
  */
 export async function spriteExec(args: SpriteExecArgs, signal?: AbortSignal): Promise<SpriteExecResult> {
   const base = resolveSpritesEndpoint(args);
-  const url = spriteExecWsUrl(base, args.id, args.cmd);
+  const url = spriteExecWsUrl(base, args.id, args.cmd, { env: args.env, dir: args.dir });
   const token = resolveSpritesToken(args.token);
   const headers: Record<string, string> = {};
   if (token) headers.Authorization = `Bearer ${token}`;
@@ -423,10 +449,12 @@ export async function spriteExec(args: SpriteExecArgs, signal?: AbortSignal): Pr
     const frames: Uint8Array[] = [];
     const ws = new WebSocket(url, { headers });
     let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
     const finish = (fn: () => void): void => {
       if (settled) return;
       settled = true;
       if (signal) signal.removeEventListener("abort", onAbort);
+      if (timer !== undefined) clearTimeout(timer);
       fn();
     };
     const onAbort = (): void => {
@@ -441,6 +469,18 @@ export async function spriteExec(args: SpriteExecArgs, signal?: AbortSignal): Pr
       if (signal.aborted) return onAbort();
       signal.addEventListener("abort", onAbort);
     }
+    if (args.timeoutMs !== undefined) {
+      timer = setTimeout(() => {
+        try {
+          ws.terminate();
+        } catch {
+          /* already closed */
+        }
+        finish(() =>
+          reject(new Error(`sprite ${args.id} exec "${args.cmd}" timed out after ${args.timeoutMs}ms`)),
+        );
+      }, args.timeoutMs);
+    }
     ws.on("open", () => {
       // No stdin: signal EOF immediately (belt and braces with stdin=false).
       ws.send(Uint8Array.of(STREAM_STDIN_EOF));

package/src/op/activity-contracts.test.ts

@@ -0,0 +1,71 @@
+import { describe, test, expect } from "vitest";
+import {
+  ConvergeOp,
+  eq,
+  isActivityContract,
+  loadActivityContracts,
+  run,
+  validateActivitySteps,
+  validateStepOutputRefs,
+  when,
+  type ActivityContract,
+  type ResourceSymptom,
+} from "@intentius/chant/op";
+import * as contracts from "./activity-contracts";
+import * as activities from "./activities";
+import { spriteServicesObserve, spriteServiceRestart } from "./builders";
+
+const CONTRACTS: Map<string, ActivityContract> = new Map(
+  Object.values(contracts).filter(isActivityContract).map((c) => [c.name, c]),
+);
+
+const op = (steps: unknown[]) => ({ name: "restart-service", phases: [{ name: "Phase", steps: steps as never[] }] });
+
+describe("fly activity contracts (#2843)", () => {
+  test("the module exports nothing but contracts, each for an exported activity, each with a return schema", () => {
+    for (const [key, value] of Object.entries(contracts)) {
+      expect(isActivityContract(value), `${key} is not an ActivityContract`).toBe(true);
+      const c = value as ActivityContract;
+      expect(typeof (activities as unknown as Record<string, unknown>)[c.name], `${c.name} is not an exported activity`).toBe("function");
+      expect(c.returns, `${c.name} declares no return schema`).toBeDefined();
+    }
+    expect([...CONTRACTS.keys()].sort()).toEqual(["spriteServiceRestart", "spriteServicesObserve"]);
+  });
+
+  test("a ConvergeOp observing spriteServicesObserve passes OPS012 and OPS013 (the guide's example)", () => {
+    const { op: converge } = ConvergeOp({
+      name: "converge",
+      env: "box",
+      dial: "apply",
+      schedule: "* * * * *",
+      observe: spriteServicesObserve({ servicesFile: "services.json" }),
+      rules: [when<ResourceSymptom>(eq("status", "drifted"), run("restart-service"), { id: "restart-drifted", why: "restart it" })],
+    });
+    const config = converge.props as never;
+    expect(validateActivitySteps(config, CONTRACTS)).toEqual([]);
+    expect(validateStepOutputRefs(config, CONTRACTS)).toEqual([]);
+  });
+
+  test("without the contracts, the same Op fails OPS013 (the bug)", () => {
+    const { op: converge } = ConvergeOp({
+      name: "converge",
+      env: "box",
+      observe: spriteServicesObserve({ servicesFile: "services.json" }),
+      rules: [when<ResourceSymptom>(eq("status", "drifted"), run("restart-service"), { id: "restart-drifted", why: "restart it" })],
+    });
+    const issues = validateStepOutputRefs(converge.props as never, new Map());
+    expect(issues.some((i) => i.message.includes("spriteServicesObserve"))).toBe(true);
+  });
+
+  test("the restart step's args validate, and a misspelled key is an error", () => {
+    expect(validateActivitySteps(op([spriteServiceRestart({ servicesFile: "services.json", waitMs: 30_000 })]), CONTRACTS)).toEqual([]);
+    const issues = validateActivitySteps(op([{ kind: "activity", fn: "spriteServiceRestart", args: { servicefile: "services.json" } }]), CONTRACTS);
+    expect(issues.some((i) => i.message.includes("servicefile"))).toBe(true);
+  });
+
+  test("loadActivityContracts finds them at @intentius/chant-lexicon-fly/op/activity-contracts", async () => {
+    const loaded = await loadActivityContracts(["fly"]);
+    expect(loaded.get("spriteServicesObserve")?.returns).toBeDefined();
+    expect(loaded.get("spriteServiceRestart")?.returns).toBeDefined();
+  });
+});

package/src/op/activity-contracts.ts

@@ -0,0 +1,67 @@
+/**
+ * Activity contracts for this lexicon's `op/activities` (chant #2101, #2843).
+ *
+ * Resolved by convention at `@intentius/chant-lexicon-fly/op/activity-contracts`:
+ * `loadActivityContracts` (`packages/core/src/op/activity-contract-registry.ts`)
+ * merges what it finds here into the map core's OPS012 and OPS013 validate
+ * every Op step against.
+ *
+ * Only the activities a step's output is referenced from are covered.
+ * `spriteServicesObserve` is the observer of a `ConvergeOp({ observe })`
+ * (#2778), whose Converge step reads the observer's whole output, so OPS013
+ * needs its return schema; without one, every project declaring such a
+ * ConvergeOp failed `chant build` and `chant lint`. `spriteServiceRestart` is
+ * the step of the Op such a ConvergeOp's rule runs, and its result is what a
+ * later step would read. The other Sprites activities have no contract yet,
+ * which OPS012 skips rather than flags.
+ *
+ * Each `args` schema mirrors the `*Args` interface in
+ * `./activities/sprite-service-converge.ts` and each `returns` schema the
+ * `*Result`. Authored with `z.strictObject(...)`, so a misspelled key fails
+ * the build instead of vanishing.
+ */
+
+import { z } from "zod";
+import { activityContract } from "@intentius/chant/op";
+
+const declaredService = z.strictObject({
+  name: z.string(),
+  health: z.string().optional(),
+  optional: z.boolean().optional(),
+});
+
+/** `Via`: the sprite for the Sprites API, or `sprite-env` inside the sprite. */
+const via = {
+  id: z.string().optional(),
+  spriteEnv: z.string().optional(),
+  endpoint: z.string().optional(),
+  token: z.string().optional(),
+};
+
+export const spriteServicesObserveContract = activityContract(
+  "spriteServicesObserve",
+  z.strictObject({
+    ...via,
+    services: z.array(declaredService).optional(),
+    servicesFile: z.string().optional(),
+    probes: z.number().optional(),
+    probeIntervalMs: z.number().optional(),
+  }),
+  z.object({
+    resources: z.array(z.object({ name: z.string(), status: z.enum(["in-sync", "drifted", "unknown"]), detail: z.string() })),
+    skipped: z.array(z.string()),
+  }),
+);
+
+export const spriteServiceRestartContract = activityContract(
+  "spriteServiceRestart",
+  z.strictObject({
+    ...via,
+    name: z.string().optional(),
+    health: z.string().optional(),
+    services: z.array(declaredService).optional(),
+    servicesFile: z.string().optional(),
+    waitMs: z.number().optional(),
+  }),
+  z.object({ name: z.string(), healthy: z.boolean().nullable() }),
+);

package/src/op/builders.ts

@@ -40,8 +40,18 @@ import type {
   SpriteServiceDeleteArgs,
   SpriteServiceLogsArgs,
 } from "./activities/sprite-services";
+import type { SpriteServicesObserveArgs, SpriteServiceRestartArgs } from "./activities/sprite-service-converge";
 import type { SpriteTaskCreateArgs, SpriteTaskRefreshArgs, SpriteTaskReleaseArgs } from "./activities/sprite-tasks";
 import type { SpritesUpArgs, SpritesDownArgs } from "./activities/sprites-emulator";
+import type {
+  FlyMachineReleaseArgs,
+  FlyMachineExecArgs,
+  FlyMachineStateArgs,
+  FlyMachineVerifyArgs,
+  FlyMachineRestoreArgs,
+} from "./activities/machine-release";
+import type { FlyReleaseArgs } from "./activities/fly-release-step";
+import type { FlyRollbackArgs } from "./activities/fly-rollback-step";
 
 type StepOpts = { profile?: ActivityStep["profile"] };
 
@@ -114,6 +124,19 @@ export const spriteServiceStop = spriteStep<SpriteServiceStopArgs>("spriteServic
 export const spriteServiceDelete = spriteStep<SpriteServiceDeleteArgs>("spriteServiceDelete", "fastIdempotent");
 /** Read a background service's log tail (#2711). Defaults to the `fastIdempotent` profile. */
 export const spriteServiceLogs = spriteStep<SpriteServiceLogsArgs>("spriteServiceLogs", "fastIdempotent");
+/**
+ * Observe a box's declared services for a ConvergeOp (#2778): one verdict per
+ * service, `in-sync`, `drifted` or `unknown`, from the supervisor's list and
+ * each service's health URL. Pass it as `ConvergeOp({ observe })`. Defaults
+ * to the `fastIdempotent` profile.
+ */
+export const spriteServicesObserve = spriteStep<SpriteServicesObserveArgs>("spriteServicesObserve", "fastIdempotent");
+/**
+ * Restart one service through its supervisor and wait for its health URL
+ * (#2778). Without `name`, the service is the one a ConvergeOp rule
+ * dispatched the run for. Defaults to the `longInfra` profile.
+ */
+export const spriteServiceRestart = spriteStep<SpriteServiceRestartArgs>("spriteServiceRestart", "longInfra");
 /** Create a keep-alive task — the fully typed twin of core's `spriteTaskCreate`. Defaults to the `fastIdempotent` profile. */
 export const spriteTaskCreate = spriteStep<SpriteTaskCreateArgs>("spriteTaskCreate", "fastIdempotent");
 /** Refresh a keep-alive task's expiry — the fully typed twin of core's `spriteTaskRefresh`. Defaults to the `fastIdempotent` profile. */
@@ -127,3 +150,37 @@ export const spritesUp = (args: WithStepRefs<SpritesUpArgs> & StepOpts = {}): Na
 /** Stop and remove the local spritzer container — the fully typed twin of core's `spritesDown`. Defaults to the `fastIdempotent` profile. */
 export const spritesDown = (args: WithStepRefs<SpritesDownArgs> & StepOpts = {}): NamedActivityStep =>
   spriteStep<SpritesDownArgs>("spritesDown", "fastIdempotent")(args);
+
+// ── Machines release activities (#2736, ws-056) ──────────────────────────────
+// The site steps as Op steps: upload and start, a migration inside the
+// Machine, restart, stop, verify and restore. Wrap a migration's
+// `flyMachineExec` in `effect()` so it fires once per environment.
+
+/** Apply the plan with the Machine serving a release (its digest in the Machine's metadata). Defaults to the `longInfra` profile. */
+export const flyMachineRelease = spriteStep<FlyMachineReleaseArgs>("flyMachineRelease", "longInfra");
+/** Run a command inside a Machine (a migration). Defaults to the `atMostOnce` profile: chant cannot know the command is safe to repeat. */
+export const flyMachineExec = spriteStep<FlyMachineExecArgs>("flyMachineExec", "atMostOnce");
+/** Restart a Machine under a lease and wait for it to be started. Defaults to the `longInfra` profile. */
+export const flyMachineRestart = spriteStep<FlyMachineStateArgs>("flyMachineRestart", "longInfra");
+/** Stop a Machine under a lease. Defaults to the `longInfra` profile. */
+export const flyMachineStop = spriteStep<FlyMachineStateArgs>("flyMachineStop", "longInfra");
+/** Check a Machine is started with a release, and its health endpoint answers. Defaults to the `longInfra` profile. */
+export const flyMachineVerify = spriteStep<FlyMachineVerifyArgs>("flyMachineVerify", "longInfra");
+/** Put a recorded Machine config back (restore, rollback). Defaults to the `longInfra` profile. */
+export const flyMachineRestore = spriteStep<FlyMachineRestoreArgs>("flyMachineRestore", "longInfra");
+/**
+ * Ship a release to a Fly Machine from an Op (#2782): the `fly-release`
+ * capability's steps (upload and start, each migration once per environment,
+ * verify, restore on failure), for the environment `environment` names. With `source`
+ * it puts an approved source tree on the Machine. Defaults to the `longInfra`
+ * profile.
+ */
+export const flyRelease = spriteStep<FlyReleaseArgs>("flyRelease", "longInfra");
+/**
+ * Put an earlier release back on a Fly Machine from an Op (#2800): the
+ * `fly-rollback` capability's restore of the Machine config recorded for `to`
+ * in `environment`, then its verify. With `source` the archive is checked
+ * against its digest, and the recorded config against the archive's tree,
+ * before the Machine changes. Defaults to the `longInfra` profile.
+ */
+export const flyRollback = spriteStep<FlyRollbackArgs>("flyRollback", "longInfra");

package/src/release-metadata.ts

@@ -0,0 +1,72 @@
+/**
+ * The release a Fly Machine serves, as its metadata records it (#2736, ws-056).
+ *
+ * Pure: the keys, a reader, and a writer over a Machine config. The Machines
+ * activities (./op/activities/machine-release.ts) stamp these on a release,
+ * `describeResources` (./describe-resources.ts) reads them back, and
+ * `chant components status --live` compares the digest with the release
+ * ledger.
+ */
+
+/**
+ * The Machine metadata keys that say which release it serves. Fly metadata is
+ * a string map, so each field is its own key.
+ *
+ * - `digest`: the release's digest, the release ledger's join key.
+ * - `gitSha`: the commit the release was built from.
+ * - `release`: an optional human label (a tag, a release id).
+ * - `previousDigest`: the release this one replaced when it first shipped, so
+ *   a rollback knows where to go back to with no history of its own.
+ */
+export const RELEASE_METADATA_KEYS = {
+  digest: "chant-release-digest",
+  gitSha: "chant-release-git-sha",
+  release: "chant-release",
+  previousDigest: "chant-release-previous-digest",
+} as const;
+
+/** A release, as a Machine's metadata records it. */
+export interface MachineRelease {
+  /** The release's digest (`sha256:...`): what the release ledger records. */
+  digest: string;
+  /** The commit it was built from. */
+  gitSha?: string;
+  /** A human label for it. */
+  release?: string;
+  /** The digest of the release it replaced, when there was one. */
+  previousDigest?: string;
+}
+
+export type MachineConfig = Record<string, unknown> & { metadata?: Record<string, string>; env?: Record<string, string> };
+
+/** The release a Machine's metadata names, or undefined when it names none. Pure. */
+export function readMachineRelease(metadata: Record<string, string> | null | undefined): MachineRelease | undefined {
+  const digest = metadata?.[RELEASE_METADATA_KEYS.digest];
+  if (!digest) return undefined;
+  const gitSha = metadata?.[RELEASE_METADATA_KEYS.gitSha];
+  const release = metadata?.[RELEASE_METADATA_KEYS.release];
+  const previousDigest = metadata?.[RELEASE_METADATA_KEYS.previousDigest];
+  return {
+    digest,
+    ...(gitSha ? { gitSha } : {}),
+    ...(release ? { release } : {}),
+    ...(previousDigest ? { previousDigest } : {}),
+  };
+}
+
+/**
+ * A Machine config serving `release`: a copy of `config` with the release's
+ * metadata keys set (and any it does not carry removed). Pure.
+ */
+export function withReleaseMetadata(config: MachineConfig | undefined, release: MachineRelease): MachineConfig {
+  const out = structuredClone(config ?? {}) as MachineConfig;
+  const metadata = { ...(out.metadata ?? {}) };
+  for (const key of Object.values(RELEASE_METADATA_KEYS)) delete metadata[key];
+  metadata[RELEASE_METADATA_KEYS.digest] = release.digest;
+  if (release.gitSha) metadata[RELEASE_METADATA_KEYS.gitSha] = release.gitSha;
+  if (release.release) metadata[RELEASE_METADATA_KEYS.release] = release.release;
+  if (release.previousDigest) metadata[RELEASE_METADATA_KEYS.previousDigest] = release.previousDigest;
+  out.metadata = metadata;
+  return out;
+}
+

package/src/release-store.ts

@@ -0,0 +1,70 @@
+/**
+ * Where a Fly release's Machine config is kept, so a rollback can put it back
+ * (#2736, ws-056).
+ *
+ * The Machine's metadata says which release it serves and which one it
+ * replaced; the config that earlier release applied is kept on the
+ * `chant/lifecycle` branch beside the release ledger, one file per release at
+ * `<env>/fly/<app>/<machine>/<digest>.json`. It is written through core's
+ * ledger plumbing, so a workspace member's copy lands under its own prefix,
+ * and every checkout that fetches the branch can roll back.
+ *
+ * Not exported from the package entry point: it spawns git, which stays off
+ * the build path. The `fly-release` and `fly-rollback` capabilities import it.
+ */
+
+import { readBlobFromPath, writeBlobToPath } from "@intentius/chant/lifecycle/git";
+
+/** Which Machine and release a config belongs to. */
+export interface MachineConfigRef {
+  app: string;
+  machine: string;
+  digest: string;
+}
+
+/** A store of the Machine config each release applied. */
+export interface MachineConfigStore {
+  read(ref: MachineConfigRef): Promise<Record<string, unknown> | undefined>;
+  write(ref: MachineConfigRef, config: Record<string, unknown>): Promise<void>;
+}
+
+const safe = (s: string) => s.replace(/[^a-zA-Z0-9_.-]/g, "_");
+
+/** The file a release's Machine config is kept in, under the environment's ledger directory. */
+export function machineConfigFile(ref: MachineConfigRef): string {
+  return `fly/${safe(ref.app)}/${safe(ref.machine)}/${safe(ref.digest.replace(/^sha256:/, ""))}.json`;
+}
+
+/** The lifecycle-branch store for `environment`. */
+export function lifecycleMachineConfigStore(environment: string, opts?: { cwd?: string }): MachineConfigStore {
+  return {
+    async read(ref) {
+      const content = await readBlobFromPath(environment, machineConfigFile(ref), opts);
+      return content === null ? undefined : (JSON.parse(content) as Record<string, unknown>);
+    },
+    async write(ref, config) {
+      await writeBlobToPath(
+        environment,
+        machineConfigFile(ref),
+        `${JSON.stringify(config, null, 2)}\n`,
+        `Fly release config ${ref.app}/${ref.machine} ${ref.digest}`,
+        opts,
+      );
+    },
+  };
+}
+
+/** An in-memory store, for tests and for a caller with nowhere to keep configs. */
+export function memoryMachineConfigStore(): MachineConfigStore & { entries: Map<string, Record<string, unknown>> } {
+  const entries = new Map<string, Record<string, unknown>>();
+  return {
+    entries,
+    async read(ref) {
+      const found = entries.get(machineConfigFile(ref));
+      return found ? structuredClone(found) : undefined;
+    },
+    async write(ref, config) {
+      entries.set(machineConfigFile(ref), structuredClone(config));
+    },
+  };
+}

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

@@ -53,3 +53,103 @@ Each prune logs the resource and endpoint it removed, so a prune run is auditabl
 ## Re-applying is safe
 
 A re-apply of an unchanged stack is a no-op per resource: machines whose config is structurally equal to live are skipped, volumes and certificates that already exist are skipped, and an IP of an already-present family is skipped. Only apply-only secrets are always re-set, because flaps exposes no value to diff against.
+
+## Releases on a Machine
+
+A component can deploy to Fly with this lexicon alone. It declares an `App` and the `Machine` that serves, builds them with `chant build --lexicon fly -o dist/fly.json`, and deploys with the `fly-release` step. Here a `Publish` phase (`publish-image`, elided) pushes the image, and the release serves it by digest:
+
+```ts
+import { phase, type Component } from "@intentius/chant/components";
+
+export const web: Component = {
+  name: "web",
+  deploy: [
+    phase("Publish", [/* publish-image */]),
+    phase("Release", [
+      {
+        kind: "fly-release",
+        plan: "dist/fly.json",
+        digest: "@Publish.digest",
+        image: "@Publish.uri",
+        migrations: [{ name: "001_init.sql", command: "node migrate.js 001_init.sql" }],
+        verify: { url: "https://web.example.com", healthPath: "/health" },
+      },
+    ]),
+  ],
+};
+```
+
+The step updates the Machine in place with the release in its `config.metadata`: `chant-release-digest`, `chant-release-git-sha` (the commit, `git rev-parse HEAD` unless given), and `chant-release-previous-digest` (the release it replaced). Each migration then runs inside the Machine through the Machines API's exec, once per environment: its receipt is kept on `chant/lifecycle` at `<env>/receipts/`, and a migration fires again only when its `sha` (or command) changes. After a migration fires, the Machine restarts, and the step checks that it is started with this release and, given a `url`, that its health endpoint answers with this commit or digest. If anything fails after the Machine changed, the step puts back the config the Machine served before (on a first release, it stops the Machine) and fails.
+
+The step's output carries `uri` and `digest`, so `chant run --components web --env prod` records the release in the ledger. `chant components status prod --live` reads the Machine's metadata back and compares its digest with the ledger's: the row is `reconciled` when they agree and `drifted` when the Machine serves something the ledger does not name. The component joins the Machine by name: name the component after the Machine entity, or list it in `liveNames`.
+
+Each release's Machine config is kept on `chant/lifecycle` at `<env>/fly/<app>/<machine>/<digest>.json`. `fly-rollback` puts back the config of the release the serving one replaced (or the digest given as `to`), checks it, and outputs that digest so the ledger records it again. `fly-release`'s own saga compensation does the same.
+
+The steps are also Op activities, for an Op that composes them itself: `flyMachineRelease`, `flyMachineExec`, `flyMachineRestart`, `flyMachineStop`, `flyMachineVerify` and `flyMachineRestore`. Wrap a migration's `flyMachineExec` in `effect()` so it fires once.
+
+### A source tree instead of an image
+
+An app with no image of its own ships as its files on the declared runtime image. Give `fly-release` a `source` in place of `image`: an archive made by core's `sourceArchive` step (`git archive` of one directory of a commit, the same bytes for the same commit), the sha256 it must have, the directory it holds, where the files go (default `/srv/app`) and the command that starts the app there. The archive is read only once its bytes hash to that digest, before the Machine changes, so the Machine never gets a tree nobody approved. The files go into the Machine's config, up to 1 MiB base64. A larger app needs an image.
+
+An Op runs the same steps with the `flyRelease` activity, which takes the environment it ships to as `environment` (`env` stays the Machine's env vars). A release Op gates on the plan core's `releasePlan` writes and records the release with `releaseRecord`:
+
+```ts
+import { Op, phase, gate, build, sourceArchive, releasePlan, releaseRecord } from "@intentius/chant/op";
+import { flyRelease } from "@intentius/chant-lexicon-fly";
+
+const archive = sourceArchive("../app", { id: "archive" });
+const plan = releasePlan({ id: "plan", component: "app", env: "fly", gitSha: archive.out.commit, content: { artifact: { digest: archive.out.digest } } });
+
+export default Op({
+  name: "release",
+  overview: "Ship the app member to Fly once its plan is approved",
+  phases: [
+    phase("Build", [archive, build(".", { script: "build:fly" })]),
+    phase("Plan", [plan]),
+    phase("Gate", [gate("ship", { plan: plan.out.digest })]),
+    phase("Ship", [
+      flyRelease({
+        environment: "fly",
+        plan: "dist/fly.json",
+        digest: plan.out.digest,
+        gitSha: archive.out.commit,
+        source: { archive: archive.out.archive, digest: archive.out.digest, dir: archive.out.dir, start: "node server.js" },
+      }),
+    ]),
+    phase("Record", [releaseRecord({ plan: plan.out.file, digest: plan.out.digest, approval: { op: "release", gate: "ship" } })]),
+  ],
+});
+```
+
+The Machine's metadata names the plan's digest, and so does the ledger record, so `chant components status fly --live` reconciles them. Running the Op again for the same commit plans the same digest, leaves the Machine as it is, and records nothing twice.
+
+### Rolling a source release back
+
+A rollback Op takes the site back to the release it served before the latest one. Core's `releaseRollbackPlan` reads the release ledger, reads the earlier release's plan back, archives the same directory of the same commit again, and refuses unless the archive hashes to the digest that plan recorded. The gate binds to the rollback plan's digest. `flyRollback` puts back the Machine config `flyRelease` recorded for that release. It checks the archive against its digest before any flaps call, and checks that the recorded config carries exactly that tree. `releaseRollbackRecord` appends the restored release with `restores`, the actor and the approver:
+
+```ts
+import { Op, phase, gate, build, releaseRollbackPlan, releaseRollbackRecord } from "@intentius/chant/op";
+import { flyRollback } from "@intentius/chant-lexicon-fly";
+
+const plan = releaseRollbackPlan({ id: "plan", component: "app", env: "fly" });
+
+export default Op({
+  name: "rollback",
+  overview: "Put the previous release back on Fly once the rollback plan is approved",
+  phases: [
+    phase("Plan", [plan, build(".", { script: "build:fly" })]),
+    phase("Gate", [gate("rollback", { plan: plan.out.digest })]),
+    phase("Roll back", [
+      flyRollback({
+        environment: "fly",
+        plan: "dist/fly.json",
+        to: plan.out.to,
+        source: { archive: plan.out.archive, digest: plan.out.archiveDigest, dir: plan.out.dir },
+      }),
+    ]),
+    phase("Record", [releaseRollbackRecord({ plan: plan.out.file, digest: plan.out.digest, approval: { op: "rollback", gate: "rollback" } })]),
+  ],
+});
+```
+
+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.

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

@@ -17,7 +17,7 @@ Each activity is a direct REST call over an injectable HTTP client, imported fro
 | Activity | What it does |
 |----------|--------------|
 | `spriteCreate` | Create a sandbox. The caller-chosen `name` becomes the sprite `id` that every later activity keys on |
-| `spriteExec` | Run a command inside the sprite. A non-zero exit throws, so the phase fails and any `onFailure` compensation runs |
+| `spriteExec` | Run a command inside the sprite, with optional `env`, `dir` and `timeoutMs` (#2765). A non-zero exit or a `timeoutMs` overrun throws, so the phase fails and any `onFailure` compensation runs |
 | `spriteCheckpoint` | Snapshot the sprite under a caller-chosen `label` |
 | `spriteRestore` | Rewind the sprite to a labeled checkpoint |
 | `spriteDestroy` | Destroy the sprite (idempotent; an already-gone sprite is a no-op) |
@@ -106,6 +106,7 @@ The same lexicon ships more Sprite primitives, all imported from `@intentius/cha
 | Filesystem (#848) | `spriteWriteFile` / `spriteReadFile` / `spriteListDir` / `spriteRemove` | stage an input file and read a result out without shelling `spriteExec` + `cat` |
 | Config reconcile (#849) | `spriteApplyNetworkPolicy` / `spriteApplyServices` | reconcile a Sprite's egress allowlist and background services against typed config (validated before any HTTP; a whole-object replace for policy, create-or-update by name for services) |
 | Services (#2711) | `spriteServiceCreate` / `spriteServiceGet` / `spriteServiceList` / `spriteServiceStart` / `spriteServiceStop` / `spriteServiceDelete` / `spriteServiceLogs` | the single-service primitives underneath `spriteApplyServices` — create-and-start one long-lived service (a box's door, hud or chud), inspect or list what's running, stop/start or delete one by name, read its log tail |
+| Converge (#2778) | `spriteServicesObserve` / `spriteServiceRestart` | keep a box's declared services running with a `ConvergeOp`: the observer step gives one verdict per service (`in-sync`, `drifted`, `unknown`) from the supervisor and each health URL, and the restart is the step of the Op a rule dispatches for the drifted service. Inside the sprite they call `sprite-env services`; with a sprite `id` they use the API |
 | Sprite URL / delete (#2711) | `spriteUrl` / `spriteDelete` | resolve a Sprite's URL, optionally waiting until a path on it answers; delete the Sprite (`spriteDelete` is `spriteDestroy` under the name spritzer/wisp and the other lexicons' delete activities use — same call, either name) |
 | Keep-alive (#847) | `spriteTaskCreate` / `spriteTaskRefresh` / `spriteTaskRelease` | hold a Sprite active for a session so it will not pause; a session past the 1-hour task cap refreshes on an interval |