@intentius/chant-lexicon-fly 0.16.0

package/src/serializer.test.ts

@@ -0,0 +1,232 @@
+import { afterEach, describe, expect, it } from "vitest";
+import type { Declarable } from "@intentius/chant";
+import { flySerializer } from "./serializer";
+import { App, Machine, MachineConfig, MachineGuest, Volume, IPAddress, Certificate, Secret } from "./generated/index";
+import { Fly } from "./pseudo";
+
+/** Author a map of declarables keyed by logical name, in insertion order. */
+function stack(...entries: Array<[string, unknown]>): Map<string, Declarable> {
+  return new Map(entries as Array<[string, Declarable]>);
+}
+
+describe("fly serializer", () => {
+  it("serializes an empty map to valid JSON", () => {
+    const result = flySerializer.serialize(new Map());
+    expect(typeof result).toBe("string");
+    expect(JSON.parse(result)).toEqual({});
+  });
+
+  it("has the correct name and rule prefix", () => {
+    expect(flySerializer.name).toBe("fly");
+    expect(flySerializer.rulePrefix).toBe("FLY");
+  });
+
+  it("emits the App create body with app_name/org_slug (flaps CreateAppRequest)", () => {
+    const entities = stack([
+      "web",
+      new App({ name: "my-app", org_slug: "acme" }),
+    ]);
+
+    const out = JSON.parse(flySerializer.serialize(entities));
+    expect(out.web).toEqual({
+      endpoint: "/v1/apps",
+      method: "POST",
+      body: { app_name: "my-app", org_slug: "acme" },
+    });
+  });
+
+  it("falls back to the entity name for app_name when no explicit name", () => {
+    const out = JSON.parse(flySerializer.serialize(stack(["billing", new App({ org_slug: "acme" })])));
+    expect(out.billing.body.app_name).toBe("billing");
+  });
+
+  it("emits the Machine create body with config image/guest and endpoints the owning app", () => {
+    const entities = stack(
+      ["app", new App({ name: "my-app", org_slug: "acme" })],
+      [
+        "api",
+        new Machine({
+          name: "api-1",
+          region: "iad",
+          config: new MachineConfig({
+            image: "flyio/hellofly:latest",
+            guest: new MachineGuest({ cpu_kind: "shared", cpus: 1, memory_mb: 256 }),
+            env: { LOG_LEVEL: "info" },
+          }),
+        }),
+      ],
+    );
+
+    const out = JSON.parse(flySerializer.serialize(entities));
+    expect(out.api.endpoint).toBe("/v1/apps/my-app/machines");
+    expect(out.api.method).toBe("POST");
+    expect(out.api.body.name).toBe("api-1");
+    expect(out.api.body.region).toBe("iad");
+    expect(out.api.body.config.image).toBe("flyio/hellofly:latest");
+    expect(out.api.body.config.guest).toEqual({ cpu_kind: "shared", cpus: 1, memory_mb: 256 });
+    expect(out.api.body.config.env).toEqual({ LOG_LEVEL: "info" });
+  });
+
+  it("stamps managed-by: chant on every machine, including one with no metadata", () => {
+    const entities = stack(
+      ["app", new App({ name: "my-app" })],
+      ["bare", new Machine({ config: new MachineConfig({ image: "nginx" }) })],
+      [
+        "withMeta",
+        new Machine({
+          config: new MachineConfig({ image: "nginx", metadata: { role: "cache" } }),
+        }),
+      ],
+    );
+
+    const out = JSON.parse(flySerializer.serialize(entities));
+    // No user metadata → marker still present.
+    expect(out.bare.body.config.metadata["managed-by"]).toBe("chant");
+    // User metadata is preserved and the marker is merged in.
+    expect(out.withMeta.body.config.metadata["managed-by"]).toBe("chant");
+    expect(out.withMeta.body.config.metadata.role).toBe("cache");
+  });
+
+  it("stamps the stack/env ownership identity when context.ownership is passed", () => {
+    const entities = stack(
+      ["app", new App({ name: "my-app" })],
+      ["api", new Machine({ config: new MachineConfig({ image: "nginx" }) })],
+    );
+
+    const out = JSON.parse(
+      flySerializer.serialize(entities, undefined, { ownership: { stack: "billing", env: "prod" } }),
+    );
+    const meta = out.api.body.config.metadata;
+    expect(meta["managed-by"]).toBe("chant");
+    expect(meta["chant-stack"]).toBe("billing");
+    expect(meta["chant-env"]).toBe("prod");
+  });
+
+  it("matches the mudflaps CreateMachineRequest field names (name/region/config)", () => {
+    const entities = stack(
+      ["app", new App({ name: "my-app" })],
+      [
+        "api",
+        new Machine({ name: "api-1", region: "iad", config: new MachineConfig({ image: "nginx" }) }),
+      ],
+    );
+    const body = JSON.parse(flySerializer.serialize(entities)).api.body;
+    // Only fields present on flaps CreateMachineRequest / MachineConfig.
+    expect(Object.keys(body).sort()).toEqual(["config", "name", "region"]);
+    expect(Object.keys(body.config.guest ?? {})).toEqual([]);
+  });
+
+  // ── #741 app-scoped, metadata-less resources ────────────────────────────────
+
+  it("emits the Volume create body (CreateVolumeRequest: name/region/size_gb/encrypted) under the app", () => {
+    const entities = stack(
+      ["app", new App({ name: "my-app" })],
+      ["data", new Volume({ name: "data", region: "iad", size_gb: 10, encrypted: true })],
+    );
+    const out = JSON.parse(flySerializer.serialize(entities));
+    expect(out.data).toEqual({
+      endpoint: "/v1/apps/my-app/volumes",
+      method: "POST",
+      body: { name: "data", region: "iad", size_gb: 10, encrypted: true },
+    });
+    // No ownership marker — metadata-less type owned at the app boundary (D2).
+    expect(out.data.body.metadata).toBeUndefined();
+  });
+
+  it("emits the IPAddress assign body (assignIPRequest: type/org_slug/...) under the app", () => {
+    const entities = stack(
+      ["app", new App({ name: "my-app" })],
+      ["ip", new IPAddress({ type: "shared_v4", region: "iad", org_slug: "acme", service_name: "web", network: "default" })],
+    );
+    const out = JSON.parse(flySerializer.serialize(entities));
+    expect(out.ip).toEqual({
+      endpoint: "/v1/apps/my-app/ip_assignments",
+      method: "POST",
+      body: { type: "shared_v4", region: "iad", org_slug: "acme", service_name: "web", network: "default" },
+    });
+  });
+
+  it("emits the Certificate create body (createCertificateRequest: hostname) under the app", () => {
+    const entities = stack(
+      ["app", new App({ name: "my-app" })],
+      ["cert", new Certificate({ hostname: "example.com" })],
+    );
+    const out = JSON.parse(flySerializer.serialize(entities));
+    expect(out.cert).toEqual({
+      endpoint: "/v1/apps/my-app/certificates",
+      method: "POST",
+      body: { hostname: "example.com" },
+    });
+  });
+
+  it("emits the Secret set body (SetAppSecretRequest: value) and flags it apply-only (D7)", () => {
+    const entities = stack(
+      ["app", new App({ name: "my-app" })],
+      ["db-password", new Secret({ value: "s3cret" })],
+    );
+    const out = JSON.parse(flySerializer.serialize(entities));
+    expect(out["db-password"]).toEqual({
+      endpoint: "/v1/apps/my-app/secrets/db-password",
+      method: "POST",
+      body: { value: "s3cret" },
+      applyOnly: true,
+    });
+  });
+});
+
+// ── Pseudo-parameters (Fly.Region / Fly.OrgSlug) ────────────────────────────
+describe("fly serializer pseudo-parameters", () => {
+  const saved = {
+    FLY_REGION: process.env.FLY_REGION,
+    FLY_ORG: process.env.FLY_ORG,
+    FLY_ORG_SLUG: process.env.FLY_ORG_SLUG,
+  };
+
+  afterEach(() => {
+    for (const [key, value] of Object.entries(saved)) {
+      if (value === undefined) delete process.env[key];
+      else process.env[key] = value;
+    }
+  });
+
+  it("resolves Fly.Region from FLY_REGION in the serialized body", () => {
+    process.env.FLY_REGION = "lhr";
+    const entities = stack(
+      ["app", new App({ name: "my-app" })],
+      ["web", new Machine({ region: Fly.Region, config: new MachineConfig({ image: "nginx" }) })],
+    );
+    const body = JSON.parse(flySerializer.serialize(entities)).web.body;
+    expect(body.region).toBe("lhr");
+  });
+
+  it("falls back to iad when FLY_REGION is unset", () => {
+    delete process.env.FLY_REGION;
+    const entities = stack(
+      ["app", new App({ name: "my-app" })],
+      ["web", new Machine({ region: Fly.Region, config: new MachineConfig({ image: "nginx" }) })],
+    );
+    const body = JSON.parse(flySerializer.serialize(entities)).web.body;
+    expect(body.region).toBe("iad");
+  });
+
+  it("resolves Fly.OrgSlug from FLY_ORG (preferred over FLY_ORG_SLUG)", () => {
+    process.env.FLY_ORG = "acme";
+    process.env.FLY_ORG_SLUG = "ignored";
+    const out = JSON.parse(flySerializer.serialize(stack(["app", new App({ name: "my-app", org_slug: Fly.OrgSlug })])));
+    expect(out.app.body.org_slug).toBe("acme");
+  });
+
+  it("resolves Fly.OrgSlug from FLY_ORG_SLUG when FLY_ORG is unset", () => {
+    delete process.env.FLY_ORG;
+    process.env.FLY_ORG_SLUG = "beta-org";
+    const out = JSON.parse(flySerializer.serialize(stack(["app", new App({ name: "my-app", org_slug: Fly.OrgSlug })])));
+    expect(out.app.body.org_slug).toBe("beta-org");
+  });
+
+  it("falls back to personal for Fly.OrgSlug when no org env var is set", () => {
+    delete process.env.FLY_ORG;
+    delete process.env.FLY_ORG_SLUG;
+    const out = JSON.parse(flySerializer.serialize(stack(["app", new App({ name: "my-app", org_slug: Fly.OrgSlug })])));
+    expect(out.app.body.org_slug).toBe("personal");
+  });
+});

package/src/serializer.ts

@@ -0,0 +1,293 @@
+/**
+ * fly (Machines API / "flaps") serializer.
+ *
+ * Turns declared `App`, `Machine`, `Volume`, `IPAddress`, `Certificate`, and
+ * `Secret` resources into the JSON create bodies the flaps REST API accepts, so
+ * #739's applier can POST them straight through and mudflaps (#740) can
+ * round-trip them.
+ *
+ * Output shape — a JSON object keyed by entity name. Each value is a single
+ * flaps request:
+ *
+ *   {
+ *     "<entityName>": {
+ *       "endpoint": "/v1/apps",                       // or /v1/apps/{app}/machines
+ *       "method": "POST",
+ *       "body": { ... }                               // the create body
+ *     }
+ *   }
+ *
+ * Field names are taken from mudflaps' Go structs (the wire oracle), which win
+ * over the OpenAPI-generated TypeScript names:
+ *   - App    → CreateAppRequest    `{ app_name, org_slug? }` (NOT `name`).
+ *   - Machine→ CreateMachineRequest `{ name?, region?, config?, skip_launch? }`;
+ *     `config` is the full MachineConfig. The owning app is a URL path segment,
+ *     not a body field, so it lands in `endpoint`.
+ *
+ * D2: every serialized Machine carries the `managed-by: chant` ownership marker
+ * (plus the stack/env identity from `context.ownership`) merged into
+ * `config.metadata`, even when the user supplied no metadata.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import { isPropertyDeclarable } from "@intentius/chant/declarable";
+import type { Serializer, SerializeContext } from "@intentius/chant/serializer";
+import type { LexiconOutput } from "@intentius/chant/lexicon-output";
+import { ownershipEntries, OWNERSHIP_MANAGED_BY_VALUE } from "@intentius/chant/ownership";
+import { walkValue, type SerializerVisitor } from "@intentius/chant/serializer-walker";
+import { INTRINSIC_MARKER } from "@intentius/chant/intrinsic";
+import { FLY_METADATA_OWNERSHIP_KEYS } from "./ownership";
+
+const APP_ENTITY_TYPE = "Fly::Machines::App";
+const MACHINE_ENTITY_TYPE = "Fly::Machines::Machine";
+const VOLUME_ENTITY_TYPE = "Fly::Machines::Volume";
+const IP_ENTITY_TYPE = "Fly::Machines::IPAddress";
+const CERTIFICATE_ENTITY_TYPE = "Fly::Machines::Certificate";
+const SECRET_ENTITY_TYPE = "Fly::Machines::Secret";
+
+/** A single flaps REST call the applier can issue verbatim. */
+interface FlapsRequest {
+  endpoint: string;
+  method: "POST";
+  body: Record<string, unknown>;
+  /**
+   * D7: apply-only resources (Secrets) are set through POST but never read back
+   * for a diff — flaps returns only a digest, never the value. The applier
+   * honors this flag by skipping the drift/diff read and always POSTing.
+   */
+  applyOnly?: boolean;
+}
+
+/**
+ * Visitor for the generic serializer walker. Property declarables (MachineConfig,
+ * MachineGuest, MachineService, ...) are unwrapped to plain objects; resource
+ * references resolve to their logical name.
+ */
+function flyVisitor(): SerializerVisitor {
+  return {
+    attrRef: (name) => name,
+    resourceRef: (name) => name,
+    propertyDeclarable: (entity, walk) => {
+      const props = (entity as unknown as { props?: unknown }).props;
+      if (!props || typeof props !== "object") return undefined;
+      const result: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(props)) {
+        if (value !== undefined) result[key] = walk(value);
+      }
+      return Object.keys(result).length > 0 ? result : undefined;
+    },
+  };
+}
+
+function readProps(entity: Declarable): Record<string, unknown> {
+  const props = (entity as unknown as { props?: unknown }).props;
+  return props && typeof props === "object" ? (props as Record<string, unknown>) : {};
+}
+
+/**
+ * Pseudo-parameter → environment variable mapping. flaps create bodies are
+ * plain JSON, so `Fly.Region` / `Fly.OrgSlug` / `Fly.AppName` (which the walker
+ * lowers to a `{ Ref: "Fly::..." }` marker) are resolved from the environment
+ * at build time, mirroring gcp's PSEUDO_ENV_MAP. The first set env var wins;
+ * absent all of them, the fallback keeps output valid offline (mudflaps).
+ */
+const PSEUDO_ENV_MAP: Record<string, { envVars: string[]; fallback: string }> = {
+  "Fly::Region": { envVars: ["FLY_REGION"], fallback: "iad" },
+  "Fly::OrgSlug": { envVars: ["FLY_ORG", "FLY_ORG_SLUG"], fallback: "personal" },
+  "Fly::AppName": { envVars: ["FLY_APP_NAME"], fallback: "app" },
+};
+
+function resolvePseudoRef(ref: string): string | undefined {
+  const mapping = PSEUDO_ENV_MAP[ref];
+  if (!mapping) return undefined;
+  for (const envVar of mapping.envVars) {
+    const value = process.env[envVar];
+    if (value) return value;
+  }
+  return mapping.fallback;
+}
+
+/**
+ * Recursively replace pseudo-parameters with their resolved environment value.
+ * Handles both a raw `PseudoParameter` instance (any intrinsic carrying the
+ * marker, unwrapped via `toJSON()`) and the already-walked `{ Ref: "Fly::X" }`
+ * shape. Non-Fly `{ Ref }` shapes and every other value pass through untouched.
+ */
+function resolvePseudoParameters(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(resolvePseudoParameters);
+  }
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+
+    // Unwrap an intrinsic (e.g. a PseudoParameter assigned without walking) to
+    // the { Ref } envelope it serializes to, then resolve that.
+    if (INTRINSIC_MARKER in record && typeof record.toJSON === "function") {
+      return resolvePseudoParameters(record.toJSON());
+    }
+
+    const keys = Object.keys(record);
+    if (keys.length === 1 && keys[0] === "Ref" && typeof record.Ref === "string") {
+      const resolved = resolvePseudoRef(record.Ref);
+      if (resolved !== undefined) return resolved;
+    }
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(record)) {
+      result[key] = resolvePseudoParameters(val);
+    }
+    return result;
+  }
+  return value;
+}
+
+/** The app_name flaps expects: an explicit `name` prop, else the entity name. */
+function appName(entity: Declarable, entityName: string): string {
+  const name = readProps(entity).name;
+  return typeof name === "string" ? name : entityName;
+}
+
+/**
+ * fly flaps serializer.
+ */
+export const flySerializer: Serializer = {
+  name: "fly",
+  rulePrefix: "FLY",
+
+  serialize(
+    entities: Map<string, Declarable>,
+    _outputs?: LexiconOutput[],
+    context?: SerializeContext,
+  ): string {
+    const entityNames = new Map<Declarable, string>();
+    for (const [name, entity] of entities) entityNames.set(entity, name);
+    const visitor = flyVisitor();
+
+    // D2 ownership marker. `managed-by: chant` is always stamped; stack/env are
+    // added when the build threads an ownership marker through the context.
+    const ownershipMeta: Record<string, string> = context?.ownership
+      ? ownershipEntries(FLY_METADATA_OWNERSHIP_KEYS, context.ownership)
+      : { [FLY_METADATA_OWNERSHIP_KEYS.managedBy]: OWNERSHIP_MANAGED_BY_VALUE };
+
+    // Resolve which app a machine belongs to (a URL path segment, not a body
+    // field). A machine may name its app explicitly via an `app` prop (a string
+    // or an `App` reference); otherwise, when the stack declares exactly one
+    // app, machines default to it. Failing both, a `{app}` placeholder is left
+    // for the applier to fill.
+    const apps: Array<[string, Declarable]> = [];
+    for (const [name, entity] of entities) {
+      if ((entity as unknown as { entityType?: string }).entityType === APP_ENTITY_TYPE) {
+        apps.push([name, entity]);
+      }
+    }
+    const soleApp = apps.length === 1 ? appName(apps[0][1], apps[0][0]) : undefined;
+
+    // The owning app of any app-scoped resource (machine, volume, ip, cert,
+    // secret): an explicit `app` prop (string or `App` reference), else the
+    // stack's sole app, else a `{app}` placeholder for the applier to fill.
+    const resolveOwningApp = (entity: Declarable): string => {
+      const app = readProps(entity).app;
+      if (typeof app === "string") return app;
+      if (app && typeof app === "object" && "entityType" in app) {
+        const decl = app as Declarable;
+        return appName(decl, entityNames.get(decl) ?? "{app}");
+      }
+      return soleApp ?? "{app}";
+    };
+
+    const requests: Record<string, FlapsRequest> = {};
+
+    for (const [name, entity] of entities) {
+      if (isPropertyDeclarable(entity)) continue;
+      const entityType = (entity as unknown as { entityType?: string }).entityType;
+      const props = readProps(entity);
+
+      if (entityType === APP_ENTITY_TYPE) {
+        const body: Record<string, unknown> = { app_name: appName(entity, name) };
+        if (props.org_slug !== undefined) body.org_slug = props.org_slug;
+        if (props.network !== undefined) body.network = props.network;
+        if (props.enable_subdomains !== undefined) body.enable_subdomains = props.enable_subdomains;
+        requests[name] = { endpoint: "/v1/apps", method: "POST", body };
+        continue;
+      }
+
+      if (entityType === MACHINE_ENTITY_TYPE) {
+        const walkedConfig = props.config
+          ? walkValue(props.config, entityNames, visitor)
+          : undefined;
+        const config: Record<string, unknown> =
+          walkedConfig && typeof walkedConfig === "object"
+            ? { ...(walkedConfig as Record<string, unknown>) }
+            : {};
+
+        // Merge the ownership marker into config.metadata. The marker wins over
+        // any colliding user key so ownership can never be silently unset.
+        const userMeta =
+          config.metadata && typeof config.metadata === "object"
+            ? (config.metadata as Record<string, unknown>)
+            : {};
+        config.metadata = { ...userMeta, ...ownershipMeta };
+
+        // Spread the create-body fields (name, region, skip_launch, ...) and
+        // override with the walked config. `app` is our association hint, not a
+        // flaps field, so it is dropped.
+        const body: Record<string, unknown> = {};
+        for (const [key, value] of Object.entries(props)) {
+          if (key === "config" || key === "app" || value === undefined) continue;
+          body[key] = walkValue(value, entityNames, visitor);
+        }
+        body.config = config;
+
+        requests[name] = {
+          endpoint: `/v1/apps/${resolveOwningApp(entity)}/machines`,
+          method: "POST",
+          body,
+        };
+        continue;
+      }
+
+      // ── App-scoped, metadata-less resources (#741, D2). ──────────────────
+      // Each spreads its scalar create-body props straight through; the `app`
+      // association hint is a URL segment, not a body field, so it is dropped.
+      // Ownership is at the app boundary, so none carry a metadata marker.
+      if (
+        entityType === VOLUME_ENTITY_TYPE ||
+        entityType === IP_ENTITY_TYPE ||
+        entityType === CERTIFICATE_ENTITY_TYPE ||
+        entityType === SECRET_ENTITY_TYPE
+      ) {
+        const app = resolveOwningApp(entity);
+
+        if (entityType === SECRET_ENTITY_TYPE) {
+          // Apply-only (D7): name is the URL segment; `value` is the only body
+          // field. mudflaps returns just a digest, so this never enters a diff.
+          const secretName = typeof props.name === "string" ? props.name : name;
+          requests[name] = {
+            endpoint: `/v1/apps/${app}/secrets/${encodeURIComponent(secretName)}`,
+            method: "POST",
+            body: props.value !== undefined ? { value: props.value } : {},
+            applyOnly: true,
+          };
+          continue;
+        }
+
+        const segment =
+          entityType === VOLUME_ENTITY_TYPE
+            ? "volumes"
+            : entityType === IP_ENTITY_TYPE
+              ? "ip_assignments"
+              : "certificates";
+        const body: Record<string, unknown> = {};
+        for (const [key, value] of Object.entries(props)) {
+          if (key === "app" || value === undefined) continue;
+          body[key] = walkValue(value, entityNames, visitor);
+        }
+        requests[name] = { endpoint: `/v1/apps/${app}/${segment}`, method: "POST", body };
+        continue;
+      }
+    }
+
+    // Resolve pseudo-parameter markers (Fly.Region, Fly.OrgSlug, ...) to their
+    // environment value so create bodies carry plain strings, not `{ Ref }`.
+    return JSON.stringify(resolvePseudoParameters(requests), null, 2);
+  },
+};

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

@@ -0,0 +1,55 @@
+---
+skill: chant-fly-ops
+description: Operate a live Fly deploy — wait on stuck machines, resolve lease conflicts, prune safely, and target a real org versus the emulator
+user-invocable: true
+---
+
+# Fly Operations Playbook
+
+This skill covers running `flyApply` against a live app: what the wait loop does, how leases resolve conflicts, when prune is safe, and how to point the same code at a real org or the mudflaps emulator. For authoring and the first deploy, see `chant-fly`; for the individual resource types, see `chant-fly-patterns`.
+
+## Targeting real Fly or the emulator
+
+The endpoint resolves in this order: an explicit `endpoint` arg, then `FLY_FLAPS_BASE_URL`, then the real-Fly default (`https://api.machines.dev`). The bearer token defaults to `FLY_API_TOKEN`.
+
+| Target | How |
+|--------|-----|
+| Local mudflaps (offline, no account) | Leave `FLY_API_TOKEN` unset and point `FLY_FLAPS_BASE_URL` at the mudflaps host (the deploy Op does this for you against a local container) |
+| Real Fly org | Set `FLY_API_TOKEN`, drop the local `FLY_FLAPS_BASE_URL` override |
+
+The same plan applies to both. The only difference is the endpoint, so the loop you test offline is the loop you ship.
+
+## Waiting for a machine to start
+
+After a create or update, `flyApply` polls `GET .../wait` until the machine reaches `started` at its new `instance_id` (its config version). flaps caps its own long-poll at 60 seconds and answers 408 when that expires, so the client re-polls until an overall deadline (300 seconds by default). A destroy waits for `state=destroyed` the same way; a reaped machine satisfies that wait.
+
+If a machine never reaches `started`:
+
+| Symptom | Likely cause | What to do |
+|---------|--------------|------------|
+| Wait keeps re-polling, machine stays in `created` or `starting` | Image pull or boot is slow, or the guest sizing is under-provisioned | Check the image reference and the `MachineGuest` values; watch the machine on the target org |
+| 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 |
+
+## 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.
+
+Conflict handling is automatic: a 409 whose body mentions a lease is a stale or lost nonce, so the applier re-acquires a fresh lease and retries the mutation once. A 409 that is not lease-shaped (for example "app already exists") is not retried. If a mutation keeps failing on a lease conflict, another operator is holding the machine; wait for their lease to clear or coordinate before re-applying.
+
+## Prune, and when it is safe
+
+Prune is off by default and destructive. It removes resources the plan no longer declares.
+
+- Machines are owned-only: a machine is pruned only if it carries the `managed-by: chant` marker. A foreign machine in the same app is never touched, so it is safe to run `flyApply` with prune against an app that also holds machines you manage elsewhere.
+- Volumes, IPs, certificates, and secrets are app-scoped, because they have no marker channel. Under a chant-managed app, anything the plan no longer declares is removed, including a resource of those types created out of band. Before enabling prune on such an app, confirm every volume, IP, certificate, and secret in it is chant-declared, and keep prune to a single chant-declared app.
+
+Each prune logs the resource and endpoint it removed, so a prune run is auditable from the Op output.
+
+## Teardown
+
+`flyDelete` is the inverse of `flyApply`: destroy the machines the plan declares (dependents first), then delete the apps. It is idempotent, so an already-absent machine or app is a no-op. The deploy Op's teardown phase uses this to tear the emulator's app down at the end of an offline loop.
+
+## 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.

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

@@ -0,0 +1,71 @@
+---
+skill: chant-fly-patterns
+description: Volumes and mounts, IP assignments, certificates, apply-only secrets, and the app-boundary ownership model for Fly
+user-invocable: true
+---
+
+# Fly Resource Patterns
+
+Beyond the App and Machine covered in `chant-fly`, the lexicon models `Volume`, `IPAddress`, `Certificate`, and `Secret`. This skill covers how they apply and prune, and the ownership boundary that makes prune safe.
+
+## Volumes and mounts
+
+`flyApply` applies volumes before machines, because a machine's `config.mounts[]` references a volume by name, so the volume must exist first. A volume is created if absent (idempotent by name); a re-apply of an existing volume is a no-op.
+
+The FLY011 build check enforces the link statically: every machine mount must reference a `Volume` declared in the stack, checked across files. A mount that points at an undeclared volume fails `chant build` before anything reaches the API.
+
+```ts
+import { App, Machine, MachineConfig, MachineGuest, Volume } from "@intentius/chant-lexicon-fly";
+
+export const app = new App({ name: "my-app" });
+
+export const data = new Volume({ name: "data", region: "iad", size_gb: 10 });
+
+export const web = new Machine({
+  name: "web",
+  region: "iad",
+  config: new MachineConfig({
+    image: "flyio/hellofly:latest",
+    guest: new MachineGuest({ cpu_kind: "shared", cpus: 1, memory_mb: 256 }),
+    mounts: [{ volume: "data", path: "/data" }],
+  }),
+});
+```
+
+## IP assignments
+
+An IP is assigned if the declared type is not already present, keyed by family (shared v4, dedicated v4, or v6). Because the address is server-allocated, a re-apply of the same declared type is a no-op rather than a second assignment.
+
+## Certificates
+
+A certificate is created if absent, idempotent by hostname. A re-apply for a hostname that already has a certificate is a no-op.
+
+## Apply-only secrets
+
+Secrets are apply-only. flaps returns only a digest for a secret, never the value, so there is nothing to read back for a diff. `flyApply` always POSTs a declared secret and excludes it from any drift comparison, so every apply re-sets it. Secret values may not be written inline in machine config (the FLY004 build check rejects that); declare them as a `Secret` or a reference.
+
+```ts
+import { Secret } from "@intentius/chant-lexicon-fly";
+
+// The value comes from the environment or a reference, not a literal in source.
+export const dbUrl = new Secret({ name: "DATABASE_URL", value: process.env.DATABASE_URL! });
+```
+
+## The app-boundary ownership model
+
+Ownership is asymmetric, by design:
+
+- Machines carry `config.metadata`, so they get the primary marker `managed-by: chant`. Prune filters on it, so a foreign machine in the same app is never touched.
+- Volumes, IPs, certificates, and secrets carry no arbitrary metadata, so they have no marker channel. Their ownership boundary is the app itself, the way a CloudFormation stack owns its resources: everything under a chant-managed app is treated as chant's, and prune for these types is app-scoped. Anything live that the plan no longer declares under that app is removed.
+
+The limitation: because these four types have no marker, a volume, IP, certificate, or secret created out of band inside a chant-managed app is indistinguishable from a chant one and can be pruned. That is the price of app-boundary ownership. The safeguard is that an app is only ever chant-managed when it carries the marker through its machines. Do not enable prune on an app that mixes chant-declared and hand-created volumes, IPs, certificates, or secrets, and never widen app-scoped prune beyond a single chant-declared app.
+
+## Apply order
+
+`flyApply` applies in dependency order and prunes last:
+
+1. Apps.
+2. Volumes (before machines, so mounts resolve).
+3. Machines (create or update, then wait for `started`; updates go through a lease).
+4. IPs, certificates, secrets (independent of machines).
+5. Prune, if enabled: machines owned-only by marker; volumes, IPs, certificates, and secrets app-scoped.