@intentius/chant-lexicon-fly 0.33.0 → 0.33.1

package/dist/codegen/package.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../src/codegen/package.ts"],"names":[],"mappings":"AAOA;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE;;;;;;;;;GAsBpF"}
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../src/codegen/package.ts"],"names":[],"mappings":"AAOA;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE;;;;;;;;;GA2BpF"}

package/dist/integrity.json

@@ -1,9 +1,19 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "4266ee314839e29c00076003edd6ae24fb9f8151c75c0af340b863d219b610df",
+    "manifest.json": "de9565b9ee89d555d1fe40b61a1bf9517277d0ec09a40224459bc9f92001b8fd",
     "meta.json": "e46e65ba7544fafc6dbb3fd48b841904b5ae6f7cb4d517a940ed68b01626c097",
-    "types/index.d.ts": "07f5d04d0d3831cae053b1f0f5dd661c58e9708f45067a0fc85dd94079ac144b"
+    "types/index.d.ts": "07f5d04d0d3831cae053b1f0f5dd661c58e9708f45067a0fc85dd94079ac144b",
+    "rules/guest-sizing.ts": "bc749d218df8f3cc3d8fbe388205ae96e6b204ae0d6d77e8bf82cb936cc53ff6",
+    "rules/no-secret-literals.ts": "4846d55118c9a66ad524b815ac28c3f548bfe114d5899e79c394f271c8b2c478",
+    "rules/valid-region.ts": "674550b3b112aa1e526572b319601dce0c1a84f537c05b1e07828f8b84511c75",
+    "rules/fly-helpers.ts": "dd29d4b520727210a56ef604a89df380f91f8b35770bc28f5c51d0f99ca92dff",
+    "rules/fly010-machine-requires-image.ts": "dd9b70ee604867a9f02334013476afcf44a78b49bbba3d66296b8ccc2b02c8a0",
+    "rules/fly011-mount-references-declared-volume.ts": "4698f73b85954a4094a1445d42336698440bf99a4004c067529c5f9fa1047cc6",
+    "skills/chant-fly.md": "04277509e0abd81869047e66c58a10f4c8eaaa60a56be28bfcbfbe1cce20ad7c",
+    "skills/chant-fly-patterns.md": "9452bf83c9e499b36a01a305a4ef28965725426436df115fd7f21e3a773f98da",
+    "skills/chant-fly-ops.md": "b8eef6504e203133e6a35c83aabb08404eec95060705395515a0046d42269cf1",
+    "skills/chant-fly-sprites.md": "89ba52db63a71a17eab483d99233a4ae67f5d34920445010e750f81c95200b4e"
   },
-  "composite": "52d33594a553b226ab907e3e03ca39a3460f054e189ae97cf77715f1ae7d4745"
+  "composite": "97f716342c879b0bf1052bda5a8e894be4f4408c1fde4c713963190be3b1d340"
 }

package/dist/manifest.json

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

package/dist/rules/fly-helpers.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared helpers for the fly post-synth checks. Not a check itself, so the
+ * generated barrel skips it (the scanner only picks up exported PostSynthChecks).
+ */
+
+/**
+ * Read an entity or property's constructor props. Nested Declarables
+ * (MachineConfig, MachineMount, Volume) stash their args under a non-enumerable
+ * `props`; a plain inline object carries them directly. Handle both so a check
+ * behaves the same whether the user authored `config: { image }` or
+ * `config: new MachineConfig({ image })`.
+ */
+export function readProps(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object") {
+    const nested = (value as { props?: unknown }).props;
+    if (nested && typeof nested === "object") return nested as Record<string, unknown>;
+    return value as Record<string, unknown>;
+  }
+  return {};
+}
+
+/** The entityType of a declarable, or undefined. */
+export function entityTypeOf(value: unknown): string | undefined {
+  return (value as { entityType?: string } | undefined)?.entityType;
+}

package/dist/rules/fly010-machine-requires-image.ts

@@ -0,0 +1,39 @@
+/**
+ * FLY010: Machine config must specify an image.
+ *
+ * A Machine cannot boot without a container image. The Machines API rejects a
+ * create request whose config omits `image`, so catch it at synth time with a
+ * clearer message.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readProps, entityTypeOf } from "./fly-helpers";
+
+export const fly010: PostSynthCheck = {
+  id: "FLY010",
+  description: "Machine config must specify an image — a Machine cannot boot without one",
+
+  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; // no config authored — a different concern
+
+      const image = readProps(config).image;
+      if (typeof image !== "string" || image.length === 0) {
+        diagnostics.push({
+          checkId: "FLY010",
+          severity: "error",
+          message: `Machine "${name}" config has no image — set config.image, e.g. image: "flyio/fastify-functions"`,
+          entity: name,
+          lexicon: "fly",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/fly011-mount-references-declared-volume.ts

@@ -0,0 +1,61 @@
+/**
+ * FLY011: A machine mount must reference a declared volume.
+ *
+ * Every machine `config.mounts[].volume` must resolve to a `Volume` declared in
+ * the stack. A mount pointing at a volume that does not exist is rejected at
+ * apply time, so catch it at synth. This is a whole-stack check: it reads all
+ * entities in the build (`ctx.entities`), so the mount and the Volume can be
+ * declared in different files.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readProps, entityTypeOf } from "./fly-helpers";
+
+const MACHINE_ENTITY_TYPE = "Fly::Machines::Machine";
+const VOLUME_ENTITY_TYPE = "Fly::Machines::Volume";
+
+export const fly011: PostSynthCheck = {
+  id: "FLY011",
+  description: "A machine mount's volume must resolve to a Volume declared in the stack",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    // A mount can name a declared volume by the Volume's `name` or by its
+    // logical (declaration) name — collect both.
+    const declaredVolumes = new Set<string>();
+    for (const [logicalName, entity] of ctx.entities) {
+      if (entityTypeOf(entity) !== VOLUME_ENTITY_TYPE) continue;
+      declaredVolumes.add(logicalName);
+      const name = readProps(entity).name;
+      if (typeof name === "string" && name.length > 0) declaredVolumes.add(name);
+    }
+
+    for (const [machineName, entity] of ctx.entities) {
+      if (entityTypeOf(entity) !== MACHINE_ENTITY_TYPE) continue;
+      const config = readProps(entity).config;
+      if (!config) continue;
+      const mounts = readProps(config).mounts;
+      if (!Array.isArray(mounts)) continue;
+
+      for (const mount of mounts) {
+        const volume = readProps(mount).volume;
+        // Only a string names a volume by value. A Declarable/AttrRef is a live
+        // reference to a Volume that exists in the stack by construction, so it
+        // never dangles — skip it to avoid false positives.
+        if (typeof volume !== "string" || volume.length === 0) continue;
+        if (!declaredVolumes.has(volume)) {
+          diagnostics.push({
+            checkId: "FLY011",
+            severity: "error",
+            message: `Machine "${machineName}" mounts volume "${volume}", which is not declared as a Volume in the stack.`,
+            entity: machineName,
+            lexicon: "fly",
+          });
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/guest-sizing.ts

@@ -0,0 +1,100 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+/**
+ * Fly guest presets, per `cpu_kind`.
+ *
+ * `cpus` is the set of valid CPU counts; `memory_mb` must be a multiple of 256
+ * within [minPerCpu * cpus, maxPerCpu * cpus]. Values mirror Fly's published
+ * guest presets (shared-cpu-Nx / performance-Nx): shared allows 256–2048 MB per
+ * CPU, performance allows 2048–8192 MB per CPU. The 256 MB step is the loosest
+ * safe multiple, so a valid config is never flagged; only clearly-invalid combos
+ * are. fly-go was not vendored in this tree to cross-check against, so this table
+ * is a documented representative set (a limitation, widen if Fly changes presets).
+ */
+const GUEST_PRESETS: Record<string, { cpus: Set<number>; minPerCpu: number; maxPerCpu: number }> = {
+  shared: { cpus: new Set([1, 2, 4, 8]), minPerCpu: 256, maxPerCpu: 2048 },
+  performance: { cpus: new Set([1, 2, 4, 8, 16]), minPerCpu: 2048, maxPerCpu: 8192 },
+};
+
+const MEMORY_STEP_MB = 256;
+
+/** Read a numeric property from an object literal, if present as a plain number literal. */
+function numberProp(obj: ts.ObjectLiteralExpression, key: string, sf: ts.SourceFile): number | undefined {
+  for (const prop of obj.properties) {
+    if (ts.isPropertyAssignment(prop) && prop.name.getText(sf) === key && ts.isNumericLiteral(prop.initializer)) {
+      return Number(prop.initializer.text);
+    }
+  }
+  return undefined;
+}
+
+/** Read a string property from an object literal, if present as a plain string literal. */
+function stringProp(obj: ts.ObjectLiteralExpression, key: string, sf: ts.SourceFile): string | undefined {
+  for (const prop of obj.properties) {
+    if (ts.isPropertyAssignment(prop) && prop.name.getText(sf) === key && ts.isStringLiteral(prop.initializer)) {
+      return prop.initializer.text;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * FLY002: Sane guest sizing
+ *
+ * A guest's `cpu_kind`, `cpus`, and `memory_mb` must be a valid combination per
+ * Fly's guest presets. An invalid combination is rejected at apply time.
+ */
+export const guestSizingRule: LintRule = {
+  id: "FLY002",
+  severity: "error",
+  category: "correctness",
+  description: "A guest's cpu_kind, cpus and memory_mb must be a valid Fly combination",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function report(node: ts.Node, message: string): void {
+      const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+      diagnostics.push({
+        file: sourceFile.fileName,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "FLY002",
+        severity: "error",
+        message,
+      });
+    }
+
+    function visit(node: ts.Node): void {
+      // A guest is any object literal carrying a cpu_kind property (new MachineGuest({...})
+      // or an inline guest object).
+      if (ts.isObjectLiteralExpression(node)) {
+        const cpuKind = stringProp(node, "cpu_kind", sourceFile);
+        if (cpuKind !== undefined) {
+          const preset = GUEST_PRESETS[cpuKind];
+          if (!preset) {
+            report(node, `Invalid guest cpu_kind "${cpuKind}". Use "shared" or "performance".`);
+          } else {
+            const cpus = numberProp(node, "cpus", sourceFile);
+            const memoryMb = numberProp(node, "memory_mb", sourceFile);
+            if (cpus !== undefined && !preset.cpus.has(cpus)) {
+              report(node, `Invalid guest sizing: cpu_kind "${cpuKind}" does not allow ${cpus} cpus (valid: ${[...preset.cpus].join(", ")}).`);
+            } else if (cpus !== undefined && memoryMb !== undefined) {
+              const min = preset.minPerCpu * cpus;
+              const max = preset.maxPerCpu * cpus;
+              if (memoryMb % MEMORY_STEP_MB !== 0 || memoryMb < min || memoryMb > max) {
+                report(node, `Invalid guest sizing: ${cpuKind}/${cpus} cpu requires memory_mb between ${min} and ${max} in steps of ${MEMORY_STEP_MB}, got ${memoryMb}.`);
+              }
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/no-secret-literals.ts

@@ -0,0 +1,67 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+/**
+ * Property names that carry a credential. Kept conservative on purpose — an
+ * inline value under one of these keys is very likely a real secret.
+ */
+const SECRET_KEY_PATTERN = /(?:^|[_-])(?:password|passwd|secret|token|api[_-]?key|apikey|access[_-]?key|secret[_-]?key|private[_-]?key|client[_-]?secret|credential|auth[_-]?token)(?:$|[_-])/i;
+
+/**
+ * Values that are references or placeholders, not literal secrets:
+ * shell/interpolation references ($FOO, ${FOO}), and secret-manager style
+ * references. These are skipped so a `secrets` reference is never flagged.
+ */
+const REFERENCE_VALUE_PATTERN = /^(?:\$\{?[A-Za-z0-9_]+\}?|(?:secret|ref|env|vault):\S+)$/;
+
+/**
+ * FLY004: No secret literals in machine config
+ *
+ * Flags secret values written inline in config (e.g. an env value under a
+ * credential-looking key). Secrets belong in `secrets` (apply-only) or a
+ * reference. The heuristic is conservative: it fires only when the property
+ * name looks like a credential AND the value is a plain string literal that is
+ * not a reference/placeholder, so a `secrets` reference (an identifier or
+ * `$FOO` placeholder) is not flagged.
+ */
+export const noSecretLiteralsRule: LintRule = {
+  id: "FLY004",
+  severity: "warning",
+  category: "security",
+  description: "Secret values must not be written inline — use secrets or a reference",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      if (ts.isPropertyAssignment(node)) {
+        const rawName = node.name.getText(sourceFile).replace(/^["']|["']$/g, "");
+        const init = node.initializer;
+        const literal =
+          ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init) ? init.text : undefined;
+
+        if (
+          literal !== undefined &&
+          literal.length >= 4 &&
+          SECRET_KEY_PATTERN.test(rawName) &&
+          !REFERENCE_VALUE_PATTERN.test(literal.trim())
+        ) {
+          const { line, character } = sourceFile.getLineAndCharacterOfPosition(init.getStart(sourceFile));
+          diagnostics.push({
+            file: sourceFile.fileName,
+            line: line + 1,
+            column: character + 1,
+            ruleId: "FLY004",
+            severity: "warning",
+            message: `Possible inline secret under "${rawName}". Move the value to \`secrets\` (apply-only) or use a reference instead of an inline literal.`,
+          });
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/rules/valid-region.ts

@@ -0,0 +1,58 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+/**
+ * Known Fly.io region codes.
+ *
+ * Sourced from the representative region list mudflaps serves at
+ * `GET /v1/platform/regions` (mudflaps `internal/server/regions.go`), which
+ * mirrors fly-go's `GetRegions` wire shape. The generated Fly types (#737)
+ * type `region` as a plain `string`, so there is no generated enum to import;
+ * this static set is the closest stable list a unit test can check without a
+ * live platform. It is representative, not exhaustive — add codes as Fly adds
+ * regions.
+ */
+const KNOWN_REGIONS = new Set<string>([
+  "ams", "atl", "bog", "bos", "cdg", "den", "dfw", "ewr", "fra", "gru",
+  "hkg", "iad", "jnb", "lax", "lhr", "mad", "mia", "nrt", "ord", "scl",
+  "sea", "sin", "sjc", "syd", "yyz",
+]);
+
+/**
+ * FLY001: Valid Fly region
+ *
+ * A machine (or volume/IP) `region` must be a known Fly region code. An unknown
+ * region is rejected at apply time; catch it at build with a clearer message.
+ */
+export const validRegionRule: LintRule = {
+  id: "FLY001",
+  severity: "error",
+  category: "correctness",
+  description: "A region must be a known Fly region code",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      if (ts.isPropertyAssignment(node) && node.name.getText(sourceFile) === "region") {
+        const init = node.initializer;
+        if (ts.isStringLiteral(init) && init.text.length > 0 && !KNOWN_REGIONS.has(init.text)) {
+          const { line, character } = sourceFile.getLineAndCharacterOfPosition(init.getStart(sourceFile));
+          diagnostics.push({
+            file: sourceFile.fileName,
+            line: line + 1,
+            column: character + 1,
+            ruleId: "FLY001",
+            severity: "error",
+            message: `Unknown Fly region "${init.text}". Use a known region code, e.g. iad, lhr, sjc, fra, syd.`,
+          });
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/dist/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/dist/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, Fly } from "@intentius/chant-lexicon-fly";
+
+export const app = new App({ name: "my-app", org_slug: Fly.OrgSlug });
+
+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.

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

@@ -0,0 +1,118 @@
+---
+skill: chant-temporal-sprites
+description: Run an agent task in a Sprite as a chant Op — create, exec, checkpoint, restore, and destroy, with checkpoint-as-compensation
+user-invocable: true
+---
+
+# Run an Agent Task in a Sprite
+
+[Sprites](https://sprites.dev) are stateful, checkpointable sandboxes. Unlike a resource lexicon, a Sprite has no desired state to reconcile: it is a runtime-orchestration primitive, the same category as `k3dUp` or `httpCheck`. So the sprite lifecycle lives in chant's Op and activity layer, not in a declarative resource type.
+
+This is the direct-API, Op-driven way to drive a Sprite: a structured, replayable activity sequence that a chant Op can checkpoint and roll back. It sits alongside the Sprites SDKs and CLI rather than replacing them, and it is not an MCP wrapper.
+
+## The five activities
+
+Each activity is a direct REST call over an injectable HTTP client, imported from `@intentius/chant-lexicon-fly` (Sprites are a Fly product, so they live in the fly lexicon alongside Machines):
+
+| 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 |
+| `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) |
+
+The sprite `id` and the checkpoint `label` are static strings the Op author writes, so nothing has to be threaded from a prior phase's output.
+
+## The happy path
+
+Compose the activities into an Op as phases:
+
+```ts
+import { Op, phase } from "@intentius/chant-lexicon-temporal";
+import { spriteCreate, spriteCheckpoint, spriteExec, spriteDestroy }
+  from "@intentius/chant-lexicon-fly";
+
+export default Op({
+  name: "agent-task",
+  overview: "Create a sprite, checkpoint, run the task, verify, destroy",
+  taskQueue: "sprites",
+  phases: [
+    phase("Create", [spriteCreate({ name: "task-1", image: "sprites/base:latest" })]),
+    phase("Checkpoint", [spriteCheckpoint({ id: "task-1", label: "pre-run" })]),
+    phase("Run", [spriteExec({ id: "task-1", cmd: "echo hello > /work/output" })]),
+    phase("Verify", [spriteExec({ id: "task-1", cmd: "cat /work/output" })]),
+    phase("Destroy", [spriteDestroy({ id: "task-1" })]),
+  ],
+});
+```
+
+There is no `build` phase and no serialized plan: the activities run in sequence. Run it with `chant run agent-task`.
+
+## Checkpoint-as-compensation
+
+The reason Sprites map onto chant Ops so well is rollback. A VM checkpoint is a fast transactional boundary. An Op checkpoints before a risky phase and, on failure, restores the labeled checkpoint instead of running an inverse action. The environment itself is the transaction, so there is nothing to unwind by hand.
+
+Put the `spriteRestore` in the Op's `onFailure`, referencing the same label the `Checkpoint` phase wrote:
+
+```ts
+import { Op, phase } from "@intentius/chant-lexicon-temporal";
+import { spriteCreate, spriteCheckpoint, spriteExec, spriteDestroy, spriteRestore }
+  from "@intentius/chant-lexicon-fly";
+
+export default Op({
+  name: "guarded-task",
+  overview: "Checkpoint, run a risky step, restore on failure",
+  taskQueue: "sprites",
+  phases: [
+    phase("Create",     [spriteCreate({ name: "task-1" })]),
+    phase("Checkpoint", [spriteCheckpoint({ id: "task-1", label: "pre-run" })]),
+    phase("Run",        [spriteExec({ id: "task-1", cmd: "./risky.sh" })]),
+    phase("Destroy",    [spriteDestroy({ id: "task-1" })]),
+  ],
+  onFailure: [
+    phase("Restore", [spriteRestore({ id: "task-1", checkpoint: "pre-run" })]),
+  ],
+});
+```
+
+When the `Run` phase's command exits non-zero, `spriteExec` throws, the phase fails, and the Op-level `onFailure` `Restore` rewinds the sprite to its `pre-run` checkpoint.
+
+## Targeting the emulator or real Sprites
+
+The activities resolve their endpoint in this order: an explicit `endpoint` arg, then `SPRITES_BASE_URL`, then the real Sprites base. The same Op targets an emulator or real Sprites with no code change. The default `fetch` client adds `Authorization: Bearer ${SPRITES_API_TOKEN}` when a token is set; the emulator ignores it.
+
+```bash
+# Point at a self-hosted or in-process emulator.
+export SPRITES_BASE_URL=http://127.0.0.1:9000
+chant run agent-task
+```
+
+```bash
+# Real Sprites: drop the override and set a token.
+unset SPRITES_BASE_URL
+export SPRITES_API_TOKEN=...
+chant run agent-task
+```
+
+The offline, Docker-free emulator that CI runs against is `createSpritesFake()` in this lexicon (`src/op/activities/sprites-fake.ts`); the activities and their tests live alongside it in `sprites.ts`. The local-emulator flow is the one to develop against.
+
+The real Sprites REST surface is provisional (S6, tracked in #766): the endpoint constants may still move to match the official API. The activity input and output contracts (the `Args` and `Result` shapes shown above) are the stable interface the Ops and the emulator are written against, so build your Ops on those.
+
+## Beyond the five: filesystem, config, and keep-alive
+
+The same lexicon ships more Sprite primitives, all imported from `@intentius/chant-lexicon-fly` and resolved by `loadActivities(["fly"])`:
+
+| Family | Activities | Use |
+|--------|-----------|-----|
+| 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) |
+| 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 |
+
+These are still runtime-orchestration primitives, not declarable resources — a Sprite has no desired-state create body to reconcile.
+
+## Where it fits
+
+The runnable starter is [`examples/sprites-agent-task`](../../examples/sprites-agent-task), which ships both Ops above. Run `chant run agent-task` for the happy path and `chant run guarded-task` to watch the checkpoint-as-compensation rollback. `guarded-task` exits non-zero on purpose: the `Run` phase fails, the `onFailure` `Restore` runs, and the sprite is back at `pre-run`.
+
+[`examples/sprites-managed-agent-worker`](../../examples/sprites-managed-agent-worker) composes the config and keep-alive families into one [Claude Managed Agents](https://docs.sprites.dev/integrations/claude-managed-agents/) session: create → egress policy → keep-alive task → env-contract file → runner-as-service → run → release → destroy, with an `onFailure` that frees the hold and tears the Sprite down.

package/dist/skills/chant-fly.md

@@ -0,0 +1,123 @@
+---
+skill: chant-fly
+description: Author, lint, and deploy Fly apps and machines from a chant project, applied straight to the Machines API
+user-invocable: true
+---
+
+# Deploy to Fly Operational Playbook
+
+## How chant and Fly relate
+
+chant is a synthesis compiler: it compiles TypeScript in `src/` into a plan of Fly Machines API ("flaps") create requests, then reconciles that plan against a Fly org. Unlike the AWS or GCP lexicons, there is no external CLI to hand off to. `flyApply` speaks the Machines API directly, so the same code that builds the plan also applies it. There is no `flyctl` shell-out and no state file to store, lock, or keep in sync.
+
+The source of truth is the TypeScript in `src/`. The serialized plan (a JSON object keyed by entity name, each value a `{ endpoint, method, body }` flaps request) is an intermediate artifact.
+
+Your job as an agent:
+
+- Use `chant build` for synthesis and lint (region, guest sizing, mounts, secret literals).
+- Use `flyApply` (via the deploy Op, `chant run`) to reconcile the plan against the Machines API: create and update machines, wait each to `started`, and optionally prune what chant owns.
+
+## The endpoint switch
+
+One environment variable decides where the same code applies:
+
+- `FLY_FLAPS_BASE_URL` unset, no token: point it at a local [mudflaps](https://github.com/intentius/mudflaps) emulator (offline, no Fly account, no bill). This is the loop CI runs.
+- `FLY_FLAPS_BASE_URL` set to a real Fly org endpoint, plus `FLY_API_TOKEN`: the same plan deploys for real.
+
+Resolution order for the endpoint is: 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`; mudflaps ignores it.
+
+Start from the runnable [`examples/local-fly`](../../examples/local-fly) loop:
+
+```bash
+cd examples/local-fly
+chant run fly        # boots mudflaps, applies an App + Machine, waits for started, tears down
+```
+
+That Op runs the phases boot, build, apply, verify, and teardown against a local mudflaps container (Docker required). To target a real org, drop the local endpoint override and set `FLY_API_TOKEN`.
+
+## Author an App and a Machine
+
+Import resource types from `@intentius/chant-lexicon-fly`. They are generated from Fly's Machines API OpenAPI spec, so `MachineConfig` is typed all the way down through guest, services, mounts, and checks.
+
+```ts
+import { App, Machine, MachineConfig, MachineGuest, Fly } from "@intentius/chant-lexicon-fly";
+
+export const app = new App({ name: "my-app", org_slug: Fly.OrgSlug });
+
+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 }),
+  }),
+});
+```
+
+A machine that names no app is bound to the stack's sole app at apply time. You do not stamp the ownership marker yourself: the serializer writes `managed-by: chant` into each machine's `config.metadata`, and the owned-only prune reads it back.
+
+The full resource set is `App`, `Machine`, `Volume`, `IPAddress`, `Certificate`, and `Secret`. Volumes, mounts, IPs, certificates, and apply-only secrets are covered in `chant-fly-patterns`.
+
+## Build and lint
+
+```bash
+chant build src/
+```
+
+Build synthesizes the flaps plan and runs the lint rules before anything reaches the API:
+
+| Rule | Catches |
+|------|---------|
+| FLY001 | `region` is not a real Fly region |
+| FLY002 | Guest sizing (`cpu_kind` / `cpus` / `memory_mb`) is not a valid combination |
+| 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) |
+
+Fix every reported violation before applying. Secret values belong in a `Secret` or a reference, never inline (FLY004).
+
+## Apply with flyApply
+
+`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).
+- 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.
+
+### Owned-only prune
+
+Prune is off by default and destructive; turn it on to remove declared-then-removed resources.
+
+- Machines prune owned-only: a machine is destroyed only if it carries the `managed-by: chant` marker and the plan no longer declares it. An unmarked (foreign) machine in the same app is never modified or deleted, so the applier is safe to point at an app that also holds resources you manage elsewhere.
+- Volumes, IPs, certificates, and secrets have no metadata channel, so their ownership boundary is the app itself. See `chant-fly-patterns` for that app-boundary model before enabling prune on an app that mixes chant and non-chant resources.
+
+## The deploy Op
+
+The lexicon ships `flyDeploy`, a composite Op that wraps the boot, build, apply, verify, and teardown phases so `chant run` drives the whole loop as modeled activities with no raw shell.
+
+```ts
+// examples/local-fly/ops/fly.op.ts
+import { flyDeploy } from "@intentius/chant-lexicon-fly";
+
+export default flyDeploy({ app: "local-fly-demo" });
+```
+
+`chant run fly` boots mudflaps, builds the plan, applies the App and Machine, waits for the machine to reach `started`, and tears the emulator down. To deploy the same Op to a real org, drop the local endpoint override and set `FLY_API_TOKEN`.
+
+## Teardown
+
+`flyDelete` is the inverse of `flyApply`: it destroys the machines the plan declares (dependents first), then deletes the apps. It is idempotent, so an already-absent resource is a no-op.
+
+## Quick reference
+
+| Command | Description |
+|---------|-------------|
+| `chant build src/` | Synthesize the flaps plan and run lint (FLY001/FLY002/FLY004/FLY010/FLY011) |
+| `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) |
+
+## Where to go next
+
+- `chant-fly-patterns` covers volumes and mounts, IP assignments, certificates, apply-only secrets, and the app-boundary ownership model.
+- `chant-fly-ops` covers operating a live app: waiting on stuck machines, lease conflicts, prune safety, and targeting a real org versus the emulator.

package/dist/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAElG,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAKvF;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAQpF"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAElG,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAgBvF;;GAEG;AACH,wBAAsB,QAAQ,CAAC,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAQpF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-fly",
-  "version": "0.33.0",
+  "version": "0.33.1",
   "type": "module",
   "files": [
     "src/",
@@ -60,7 +60,7 @@
     "@intentius/chant": "^0.33.0",
     "typescript": "^5.9.3"
   },
-  "description": "Google Cloud lexicon for chant — declarative IaC in TypeScript",
+  "description": "Fly.io Machines lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -75,7 +75,7 @@
     "infrastructure-as-code",
     "iac",
     "typescript",
-    "google-cloud",
+    "fly-io",
     "chant"
   ]
 }

package/src/codegen/package.ts

@@ -1,6 +1,6 @@
-import { packagePipeline } from "@intentius/chant/codegen/package";
-import type { PackagePipelineConfig } from "@intentius/chant/codegen/package";
+import { packagePipeline, collectSkills } from "@intentius/chant/codegen/package";
 import { generate } from "./generate";
+import { flyPlugin } from "../plugin";
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
@@ -9,8 +9,12 @@ import { fileURLToPath } from "url";
  * Package the fly lexicon for distribution.
  */
 export async function packageLexicon(options?: { verbose?: boolean; force?: boolean }) {
-  const srcDir = dirname(fileURLToPath(import.meta.url));
-  const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "..", "package.json"), "utf-8"));
+  // This file is src/codegen/package.ts — rules and skills are collected
+  // relative to src/, so srcDir must be the parent of this directory.
+  // Pointing it at src/codegen made collectRules glob a directory that does
+  // not exist, and the bundle shipped zero rules alongside zero skills.
+  const srcDir = dirname(dirname(fileURLToPath(import.meta.url)));
+  const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));
 
   const { spec, stats } = await packagePipeline({
     generate: (opts) => generate({ verbose: opts?.verbose, force: opts?.force }),
@@ -18,16 +22,17 @@ export async function packageLexicon(options?: { verbose?: boolean; force?: bool
     // (a hardcoded "0.0.1", never the real package version), so
     // `dist/manifest.json` shipped without a chantVersion at all. Matches
     // the shape every other lexicon's codegen/package.ts already uses.
-    buildManifest: (genResult) => ({
+    buildManifest: (_genResult) => ({
       name: "fly",
       version: pkgJson.version ?? "0.0.0",
       chantVersion: ">=0.1.0",
       namespace: "Fly",
     }),
     srcDir,
-    collectSkills: () => new Map(),
+    collectSkills: () => collectSkills(flyPlugin.skills?.() ?? []),
   });
 
-  console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules`);
+  // Both callers (the plugin's package() and package-cli) print their own
+  // summary — don't double-report here.
   return { spec, stats };
 }

package/src/package-cli.ts

@@ -20,5 +20,7 @@ const force = process.argv.includes("--force");
 const { spec, stats } = await packageLexicon({ verbose, force });
 writeBundleSpec(spec, distDir);
 
-console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules`);
+console.error(
+  `Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`,
+);
 console.error(`dist/ written to ${distDir}`);

package/src/validate.ts

@@ -11,8 +11,19 @@ import { validateLexiconArtifacts, type ValidateResult } from "@intentius/chant/
 
 export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
 
-// TODO: Add names of required entities for your lexicon
-const REQUIRED_NAMES: string[] = [];
+/**
+ * The curated top-level Machines API resources (#741). A regeneration that
+ * loses one — an upstream rename, a spec fetch that returned a partial
+ * document — must fail validation rather than ship a lexicon missing a kind.
+ */
+const REQUIRED_NAMES: string[] = [
+  "App",
+  "Machine",
+  "Volume",
+  "IPAddress",
+  "Certificate",
+  "Secret",
+];
 
 /**
  * Validate the generated lexicon-fly artifacts.