@intentius/chant-lexicon-fly 0.124.30 → 0.124.32

package/dist/op/builders.js

@@ -0,0 +1,157 @@
+/**
+ * Typed step-builder wrappers for this lexicon's sprite activities (chant
+ * #1288 Stage 2 — "regenerate the step builders as fully typed wrappers").
+ * Core's own sprite builders (`spriteCreate`, `spriteExec`, ...) already
+ * carry an inline object-literal type in `packages/core/src/op/builders.ts`
+ * — but that inline type is a hand-restated MIRROR of this lexicon's own
+ * `Sprite*Args` interfaces (`./activities/sprites.ts`,
+ * `./activities/sprite-fs.ts`, `./activities/sprite-tasks.ts`,
+ * `./activities/sprite-config.ts`, `./activities/sprites-emulator.ts`),
+ * exactly the duplication Stage 2 exists to eliminate. `opts`'s type in
+ * every wrapper below IS the activity's own `*Args` interface (via
+ * `WithStepRefs`) — never restated — so it stays in sync with the
+ * implementation by construction.
+ *
+ * There's no cross-package layering problem here (unlike `kubectlApply`/
+ * `helmInstall`): this package already owns both the activities and (per
+ * `./composites/fly-deploy.ts`'s existing `flapsUp`/`flapsDown`/
+ * `flyApplyStep` precedent, #744) the step-builder layer. So — matching how
+ * `packages/core/src/op/builders.ts` handles ITS OWN activities — this
+ * module REPLACES (not adds alongside) the sprite builders this package's
+ * `src/index.ts` used to re-export from `@intentius/chant/op`: same names,
+ * same import path (`@intentius/chant-lexicon-fly`), so an existing
+ * `import { spriteCreate } from "@intentius/chant-lexicon-fly"` call site
+ * gains authoring-time types and `StepOutputRef`/`.out` support with no
+ * change. `core`'s own originals are untouched, for anyone still importing
+ * `@intentius/chant/op` directly.
+ */
+import { activity } from "@intentius/chant/op";
+/**
+ * Build one whole-args typed sprite step builder — `args` IS the activity's
+ * own `*Args` type, `profile` routed off it, never restated. Only `profile`
+ * is extracted, deliberately NOT a step-authoring `id` the way the other
+ * lexicons' wrappers offer: `id` is itself a REQUIRED domain field on nearly
+ * every `Sprite*Args` here (the target sprite's id — `spriteExec`,
+ * `spriteWriteFile`, `spriteTaskCreate`, ...), so stripping an `id` key off
+ * the flat args object the way `takeProfileAndId` does elsewhere would
+ * silently steal the sprite id into the step's `id` and drop it from `args`
+ * — the exact silent-wrong-value failure class chant #1288 exists to catch,
+ * not reproduce. `.out`-by-id (#1290) is out of scope for the sprite family
+ * through this convenience layer, exactly as it was through core's original
+ * builders; an author who needs it authors `activity("spriteExec", args, {
+ * id: "..." })` directly. `Args` is deliberately unconstrained: a named
+ * interface without an explicit index signature (every `Sprite*Args` here)
+ * is not assignable to `Record<string, unknown>` structurally, even though
+ * every field it does declare is — the `as Record<string, unknown>` cast
+ * below is a type ASSERTION (permissive), not an assignment, so it doesn't
+ * need the constraint.
+ */
+function spriteStep(fn, defaultProfile) {
+    return (args) => {
+        const { profile, ...rest } = args;
+        return activity(fn, rest, profile ?? defaultProfile);
+    };
+}
+/** Create a sprite — the fully typed twin of core's `spriteCreate`. Defaults to the `longInfra` profile. */
+export const spriteCreate = spriteStep("spriteCreate", "longInfra");
+/** Run a command in a sprite — the fully typed twin of core's `spriteExec`. Defaults to the `longInfra` profile. */
+export const spriteExec = spriteStep("spriteExec", "longInfra");
+/** Checkpoint a sprite — the fully typed twin of core's `spriteCheckpoint`. Defaults to the `longInfra` profile. */
+export const spriteCheckpoint = spriteStep("spriteCheckpoint", "longInfra");
+/** Restore a sprite — the fully typed twin of core's `spriteRestore`. Defaults to the `longInfra` profile. */
+export const spriteRestore = spriteStep("spriteRestore", "longInfra");
+/** List a sprite's checkpoints — the fully typed twin of core's `listCheckpoints`. Defaults to the `fastIdempotent` profile. */
+export const listCheckpoints = spriteStep("listCheckpoints", "fastIdempotent");
+/** Destroy a sprite — the fully typed twin of core's `spriteDestroy`. Defaults to the `fastIdempotent` profile. */
+export const spriteDestroy = spriteStep("spriteDestroy", "fastIdempotent");
+/** Delete a sprite (#2711; alias of `spriteDestroy`). Defaults to the `fastIdempotent` profile. */
+export const spriteDelete = spriteStep("spriteDelete", "fastIdempotent");
+/** Resolve a sprite's URL, optionally waiting until a path on it answers (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteUrl = spriteStep("spriteUrl", "fastIdempotent");
+/** Write a file into a sprite — the fully typed twin of core's `spriteWriteFile`. Defaults to the `fastIdempotent` profile. */
+export const spriteWriteFile = spriteStep("spriteWriteFile", "fastIdempotent");
+/** Read a file from a sprite — the fully typed twin of core's `spriteReadFile`. Defaults to the `fastIdempotent` profile. */
+export const spriteReadFile = spriteStep("spriteReadFile", "fastIdempotent");
+/** List a directory in a sprite — the fully typed twin of core's `spriteListDir`. Defaults to the `fastIdempotent` profile. */
+export const spriteListDir = spriteStep("spriteListDir", "fastIdempotent");
+/** Remove a path in a sprite — the fully typed twin of core's `spriteRemove`. Defaults to the `fastIdempotent` profile. */
+export const spriteRemove = spriteStep("spriteRemove", "fastIdempotent");
+/** Reconcile a sprite's outbound network policy — the fully typed twin of core's `spriteApplyNetworkPolicy`. Defaults to the `fastIdempotent` profile. */
+export const spriteApplyNetworkPolicy = spriteStep("spriteApplyNetworkPolicy", "fastIdempotent");
+/**
+ * Reconcile a sprite's background services — the fully typed twin of core's
+ * `spriteApplyServices`. With an `id`, through the Sprites API; without one,
+ * inside the sprite through sprite-env, applying the box block's services
+ * (`box: true`, with `only`, `start` and `restart`, #2880). Defaults to the
+ * `fastIdempotent` profile.
+ */
+export const spriteApplyServices = spriteStep("spriteApplyServices", "fastIdempotent");
+/** Create-and-start one background service (#2711) — the single-service primitive underneath `spriteApplyServices`. Defaults to the `longInfra` profile (the create+start NDJSON round trip). */
+export const spriteServiceCreate = spriteStep("spriteServiceCreate", "longInfra");
+/** Get one background service's definition and live state (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteServiceGet = spriteStep("spriteServiceGet", "fastIdempotent");
+/** List a sprite's background services (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteServiceList = spriteStep("spriteServiceList", "fastIdempotent");
+/** Start a stopped background service (#2711). Defaults to the `longInfra` profile (the NDJSON round trip). */
+export const spriteServiceStart = spriteStep("spriteServiceStart", "longInfra");
+/** Stop a running background service (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteServiceStop = spriteStep("spriteServiceStop", "fastIdempotent");
+/** Delete a background service, idempotent (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteServiceDelete = spriteStep("spriteServiceDelete", "fastIdempotent");
+/** Read a background service's log tail (#2711). Defaults to the `fastIdempotent` profile. */
+export const spriteServiceLogs = spriteStep("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("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("spriteServiceRestart", "longInfra");
+/** Create a keep-alive task — the fully typed twin of core's `spriteTaskCreate`. Defaults to the `fastIdempotent` profile. */
+export const spriteTaskCreate = spriteStep("spriteTaskCreate", "fastIdempotent");
+/** Refresh a keep-alive task's expiry — the fully typed twin of core's `spriteTaskRefresh`. Defaults to the `fastIdempotent` profile. */
+export const spriteTaskRefresh = spriteStep("spriteTaskRefresh", "fastIdempotent");
+/** Release a keep-alive task — the fully typed twin of core's `spriteTaskRelease`. Defaults to the `fastIdempotent` profile. */
+export const spriteTaskRelease = spriteStep("spriteTaskRelease", "fastIdempotent");
+/** Boot a local spritzer (Fly Sprites API emulator) — the fully typed twin of core's `spritesUp`. Defaults to the `longInfra` profile. */
+export const spritesUp = (args = {}) => spriteStep("spritesUp", "longInfra")(args);
+/** Stop and remove the local spritzer container — the fully typed twin of core's `spritesDown`. Defaults to the `fastIdempotent` profile. */
+export const spritesDown = (args = {}) => spriteStep("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("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("flyMachineExec", "atMostOnce");
+/** Restart a Machine under a lease and wait for it to be started. Defaults to the `longInfra` profile. */
+export const flyMachineRestart = spriteStep("flyMachineRestart", "longInfra");
+/** Stop a Machine under a lease. Defaults to the `longInfra` profile. */
+export const flyMachineStop = spriteStep("flyMachineStop", "longInfra");
+/** Check a Machine is started with a release, and its health endpoint answers. Defaults to the `longInfra` profile. */
+export const flyMachineVerify = spriteStep("flyMachineVerify", "longInfra");
+/** Put a recorded Machine config back (restore, rollback). Defaults to the `longInfra` profile. */
+export const flyMachineRestore = spriteStep("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("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("flyRollback", "longInfra");

package/dist/ownership.js

@@ -0,0 +1,29 @@
+/**
+ * The fly lexicon's ownership convention (#743, decision D2), declared here so
+ * core carries no fly-specific branch — the #686 seam: each lexicon owns its key
+ * names; core keeps only the generic stamp/detect logic
+ * (@intentius/chant/ownership), the same way aws declares `AWS_TAG_OWNERSHIP_KEYS`
+ * and azure `AZURE_TAG_OWNERSHIP_KEYS`.
+ *
+ * The convention is two-tier, because flaps resources differ in what they can
+ * carry:
+ *
+ *   1. Primary marker — machine `config.metadata`. Machines carry a flat
+ *      `Record<string, string>`, so chant stamps `managed-by: chant` (+ stack/env)
+ *      there. This is the k8s-label / AWS-tag analogue and the basis for
+ *      owned-only machine prune (a metadata filter — a foreign machine survives).
+ *      The serializer stamps it (see serializer.ts); the applier reads it via
+ *      `isChantOwned` → core `hasOwnershipMarker(..., FLY_METADATA_OWNERSHIP_KEYS)`.
+ *
+ *   2. Secondary boundary — the app. Volumes, secrets, certs, and IPs carry no
+ *      arbitrary metadata, so for them the Fly app is the ownership boundary
+ *      (like a CloudFormation stack): chant owns the app's declared-type
+ *      resources and prunes owned orphans within app scope. See the app-scoped
+ *      prune block in op/activities/fly-apply.ts for the limitation this leaves.
+ */
+/** Machine `config.metadata` keys for chant's ownership markers (tier 1, D2). */
+export const FLY_METADATA_OWNERSHIP_KEYS = {
+    managedBy: "managed-by",
+    stack: "chant-stack",
+    env: "chant-env",
+};

package/dist/package-cli.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env tsx
+/**
+ * Thin entry point for `npm run bundle` in lexicon-fly.
+ * Generates src/generated/ files and writes dist/ bundle.
+ *
+ * NOTE: Uses top-level await (matching AWS/Azure pattern) to avoid
+ * event loop references from async wrappers keeping the process alive.
+ */
+import { packageLexicon } from "./codegen/package.js";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+const pkgDir = dirname(fileURLToPath(import.meta.url));
+const distDir = join(pkgDir, "..", "dist");
+const verbose = process.argv.includes("--verbose") || !process.argv.includes("--quiet");
+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, ${stats.skillCount} skills`);
+console.error(`dist/ written to ${distDir}`);

package/dist/plugin.js

@@ -0,0 +1,298 @@
+import { compositeCatalog } from "./composites/catalog.js";
+import { createSkillsLoader } from "@intentius/chant/lexicon-plugin-helpers";
+import { MUDFLAPS_EMULATOR } from "./op/activities/flaps.js";
+import { SPRITZER_EMULATOR } from "./op/activities/sprites-emulator.js";
+import { flyAuditCatalog } from "./lint/audit-catalog.js";
+import { flySerializer } from "./serializer.js";
+import { rules } from "./lint/rules/index.js";
+import { postSynthChecks } from "./lint/post-synth/index.js";
+import { completions } from "./lsp/completions.js";
+import { hover } from "./lsp/hover.js";
+import { detectTemplate as detectFlyTemplate } from "./detect.js";
+import { FlyParser } from "./import/parser.js";
+import { FlyGenerator } from "./import/generator.js";
+import { flyReferenceCatalog } from "./reference-catalog.js";
+import { flyContextTools } from "./mcp/context-tools.js";
+import { FLY_METADATA_OWNERSHIP_KEYS } from "./ownership.js";
+/**
+ * fly lexicon plugin.
+ *
+ * Implements all required LexiconPlugin lifecycle methods.
+ */
+export const flyPlugin = {
+    name: "fly",
+    ownershipChannel: { keys: FLY_METADATA_OWNERSHIP_KEYS, reads: ["describeResources"] },
+    // Two: the Machines API and Sprites (#1345).
+    emulator: [MUDFLAPS_EMULATOR, SPRITZER_EMULATOR],
+    auditCatalog: () => flyAuditCatalog,
+    serializer: flySerializer,
+    // ── Required lifecycle methods ────────────────────────────────
+    async generate(options) {
+        const { generate } = await import("./codegen/generate.js");
+        await generate(options);
+    },
+    async validate(options) {
+        const { validate } = await import("./validate.js");
+        const { printValidationResult } = await import("@intentius/chant/codegen/validate");
+        const result = await validate();
+        printValidationResult(result);
+    },
+    async coverage(options) {
+        const { analyzeFlyCoverage } = await import("./coverage.js");
+        await analyzeFlyCoverage({ verbose: options?.verbose, minOverall: options?.minOverall });
+    },
+    async package(options) {
+        const { packageLexicon } = await import("./codegen/package.js");
+        const { writeBundleSpec } = await import("@intentius/chant/codegen/package");
+        const { join, dirname } = await import("path");
+        const { fileURLToPath } = await import("url");
+        const { spec, stats } = await packageLexicon(options);
+        const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+        writeBundleSpec(spec, join(pkgDir, "dist"));
+        console.error(`Packaged ${stats.resources} resources, ${stats.ruleCount} rules, ${stats.skillCount} skills`);
+    },
+    // ── Optional extensions ────────────────────────────────────
+    lintRules() {
+        return rules;
+    },
+    postSynthChecks() {
+        return postSynthChecks;
+    },
+    skills: createSkillsLoader(import.meta.url, [
+        {
+            file: "chant-fly.md",
+            name: "chant-fly",
+            description: "Author, lint, and deploy Fly apps and machines from a chant project, applied straight to the Machines API",
+            triggers: [
+                { type: "file-pattern", value: "*.fly.ts" },
+                { type: "context", value: "fly" },
+                { type: "context", value: "fly.io" },
+            ],
+            parameters: [
+                {
+                    name: "resourceType",
+                    type: "string",
+                    description: "Fly resource type to work with (App, Machine, Volume, IPAddress, Certificate, Secret)",
+                },
+            ],
+            examples: [
+                {
+                    title: "Author an App and a Machine",
+                    output: "new App({ name: \"my-app\", org_slug: Fly.OrgSlug });\nnew Machine({ region: \"iad\", config: new MachineConfig({ image: \"flyio/hellofly:latest\" }) })",
+                },
+                {
+                    title: "Deploy against mudflaps offline",
+                    input: "Apply the App + Machine without a Fly account",
+                    output: "cd examples/local-fly && chant run fly",
+                },
+            ],
+        },
+        {
+            file: "chant-fly-patterns.md",
+            name: "chant-fly-patterns",
+            description: "Volumes and mounts, IP assignments, certificates, apply-only secrets, and the app-boundary ownership model for Fly",
+            triggers: [
+                { type: "context", value: "fly volumes" },
+                { type: "context", value: "fly secrets" },
+                { type: "context", value: "fly certificates" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Machine with a mounted volume",
+                    input: "Attach a volume to a machine",
+                    output: "new Volume({ name: \"data\", region: \"iad\", size_gb: 10 });\nnew Machine({ config: new MachineConfig({ mounts: [{ volume: \"data\", path: \"/data\" }] }) })",
+                },
+            ],
+        },
+        {
+            file: "chant-fly-ops.md",
+            name: "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",
+            triggers: [
+                { type: "context", value: "fly apply" },
+                { type: "context", value: "fly prune" },
+                { type: "context", value: "flaps lease" },
+            ],
+            parameters: [],
+            examples: [
+                {
+                    title: "Deploy to a real Fly org",
+                    input: "Point the same code at a real org",
+                    output: "export FLY_API_TOKEN=... && chant run fly",
+                },
+            ],
+        },
+        {
+            file: "chant-fly-sprites.md",
+            name: "chant-fly-sprites",
+            description: "Run an agent task in a Sprite as a chant Op — create, exec, checkpoint, restore, destroy, with checkpoint-as-compensation",
+            triggers: [
+                { type: "context", value: "sprite" },
+                { type: "context", value: "sprites.dev" },
+                { type: "context", value: "agent sandbox" },
+                { type: "context", value: "checkpoint compensation" },
+            ],
+            parameters: [],
+            examples: [],
+        },
+    ]),
+    composites() {
+        return compositeCatalog;
+    },
+    mcpTools() {
+        return flyContextTools();
+    },
+    mcpResources() {
+        // No standing MCP resources: Fly's read-only context is the fly:* tools above
+        // (build-from-source) plus the chant-fly skills. There's no static catalog or
+        // per-project artifact to expose as a resource.
+        return [];
+    },
+    detectTemplate(data) {
+        return detectFlyTemplate(data);
+    },
+    templateParser() {
+        return new FlyParser();
+    },
+    templateGenerator() {
+        return new FlyGenerator();
+    },
+    pseudoParameters() {
+        return [
+            "Fly::Region",
+            "Fly::OrgSlug",
+            "Fly::AppName",
+        ];
+    },
+    initTemplates(template) {
+        if (template === "volume") {
+            return {
+                src: {
+                    "infra.ts": `import { App, Machine, MachineConfig, MachineGuest, MachineMount, Volume, Fly } from "@intentius/chant-lexicon-fly";
+
+// An app, a persistent volume, and a machine that mounts it. The serializer
+// (#738) turns these into the flaps create bodies flyApply POSTs. The region
+// comes from Fly.Region (resolved from FLY_REGION, defaulting to "iad").
+const app = new App({ name: "my-app", org_slug: Fly.OrgSlug });
+
+const data = new Volume({
+  name: "data",
+  region: Fly.Region,
+  size_gb: 10,
+});
+
+const web = new Machine({
+  name: "web",
+  region: Fly.Region,
+  config: new MachineConfig({
+    image: "flyio/hellofly:latest",
+    guest: new MachineGuest({ cpu_kind: "shared", cpus: 1, memory_mb: 256 }),
+    mounts: [new MachineMount({ volume: "data", path: "/data" })],
+  }),
+});
+
+export { app, data, web };
+`,
+                },
+            };
+        }
+        if (template === "service") {
+            return {
+                src: {
+                    "infra.ts": `import { App, Machine, MachineConfig, MachineGuest, MachineService, MachinePort, Fly } from "@intentius/chant-lexicon-fly";
+
+// An app and a machine exposing a public HTTPS service on port 443 to internal
+// 8080. The region comes from Fly.Region (resolved from FLY_REGION, defaulting
+// to "iad").
+const app = new App({ name: "my-app", org_slug: Fly.OrgSlug });
+
+const web = new Machine({
+  name: "web",
+  region: Fly.Region,
+  config: new MachineConfig({
+    image: "flyio/hellofly:latest",
+    guest: new MachineGuest({ cpu_kind: "shared", cpus: 1, memory_mb: 256 }),
+    services: [
+      new MachineService({
+        protocol: "tcp",
+        internal_port: 8080,
+        ports: [new MachinePort({ port: 443, handlers: ["tls", "http"] })],
+      }),
+    ],
+  }),
+});
+
+export { app, web };
+`,
+                },
+            };
+        }
+        // Default: one app and one machine — the smallest complete deploy.
+        return {
+            src: {
+                "infra.ts": `import { App, Machine, MachineConfig, MachineGuest, Fly } from "@intentius/chant-lexicon-fly";
+
+// One Fly app and one machine — the smallest complete deploy. The serializer
+// (#738) turns these into the flaps create bodies flyApply POSTs. The region
+// comes from Fly.Region (resolved from FLY_REGION, defaulting to "iad").
+const app = new App({ name: "my-app", org_slug: Fly.OrgSlug });
+
+const web = new Machine({
+  name: "web",
+  region: Fly.Region,
+  config: new MachineConfig({
+    image: "flyio/hellofly:latest",
+    guest: new MachineGuest({ cpu_kind: "shared", cpus: 1, memory_mb: 256 }),
+  }),
+});
+
+export { app, web };
+`,
+            },
+        };
+    },
+    completionProvider(ctx) {
+        return completions(ctx);
+    },
+    hoverProvider(ctx) {
+        return hover(ctx);
+    },
+    async docs(options) {
+        const { generateDocs } = await import("./codegen/docs.js");
+        return generateDocs(options);
+    },
+    // State: the read-back seam for plan + drift (#767). Lists live Fly resources
+    // over flaps, keyed by chant entity name, with an ownership verdict core's
+    // change set reads. Endpoint + auth reuse the applier (FLY_FLAPS_BASE_URL /
+    // FLY_API_TOKEN), so it reads the same target flyApply writes.
+    async describeResources(options) {
+        const { describeResources } = await import("./describe-resources.js");
+        return describeResources(options);
+    },
+    // Env teardown (#1222): enumeration + execution over the machine marker
+    // (`managed-by` + `chant-stack` + `chant-env`) and the app boundary (#743).
+    // Machines are destroyed first, whole apps last — an app hosting any machine
+    // outside the requested identity is never deleted whole. See ./teardown.ts.
+    async teardownOwned(options) {
+        const { teardownOwned } = await import("./teardown.js");
+        return teardownOwned(options);
+    },
+    async executeTeardown(options) {
+        const { executeTeardown } = await import("./teardown.js");
+        return executeTeardown(options);
+    },
+    // Live export (cloud → code): read live flaps state and regenerate App/Machine
+    // TypeScript. Strips server-written fields to the authored shape; honors the
+    // `owned` filter (machine marker; app-boundary inference for the marker-less
+    // app, logged per the seam contract). Reuses the applier's endpoint/auth and
+    // listMachines so it reads the same target flyApply writes.
+    async exportResources(options) {
+        const { exportResources } = await import("./export-resources.js");
+        return exportResources(options);
+    },
+    // Live graph edges (#804): how observed Fly resources reference each other, so
+    // `chant graph --live` reconstructs the topology (App boundary + mount edges).
+    // No `enrichLiveAttrs` needed — describeResources already returns rich attrs.
+    referenceCatalog: flyReferenceCatalog,
+};

package/dist/pseudo.js

@@ -0,0 +1,26 @@
+import { PseudoParameter, createPseudoParameters } from "@intentius/chant/pseudo-parameter";
+export { PseudoParameter };
+/**
+ * Fly pseudo-parameters — environment-resolved values a project references
+ * without hard-coding. Each serializes to a `{ Ref: "Fly::..." }` marker that
+ * the serializer resolves from an environment variable at build time (see
+ * PSEUDO_ENV_MAP in ./serializer.ts), mirroring gcp's `GCP.Region` /
+ * `GCP.ProjectId`.
+ *
+ *   - Region  → the target Fly region (FLY_REGION), e.g. `iad`.
+ *   - OrgSlug → the owning org slug (FLY_ORG / FLY_ORG_SLUG).
+ *   - AppName → the target app name (FLY_APP_NAME).
+ */
+export const { Region, OrgSlug, AppName } = createPseudoParameters({
+    Region: "Fly::Region",
+    OrgSlug: "Fly::OrgSlug",
+    AppName: "Fly::AppName",
+});
+/**
+ * Fly namespace containing all pseudo-parameters.
+ */
+export const Fly = {
+    Region,
+    OrgSlug,
+    AppName,
+};

package/dist/reference-catalog.js

@@ -0,0 +1,37 @@
+/**
+ * Fly reference catalog (#804) — how observed Fly resources reference each other,
+ * so `chant graph --live` reconstructs the topology and draws the App as a
+ * boundary box (the reference resolver, chant#778; containment, chant#779).
+ *
+ * Fly's relationships are app-centric and simple. `describeResources`
+ * (./describe-resources.ts) already returns the rich per-resource shape — each
+ * app-scoped resource carries its owning `app`, and a machine carries its full
+ * `config` (with `mounts`) — so, unlike AWS (chant#784), Fly needs **no**
+ * `enrichLiveAttrs`: the references are already in the observed attributes.
+ *
+ * Keyed to the `describeResources` attribute shape:
+ *   - App        → `{ app }`           (physicalId = app name)
+ *   - Machine    → `{ app, config }`   (config.mounts[].volume references a Volume)
+ *   - Volume     → `{ app, volumeName }`
+ *   - IPAddress  → `{ app, ... }`
+ *   - Certificate→ `{ app, ... }`
+ */
+export const flyReferenceCatalog = {
+    identities: [
+        // The App is identified by its name (also its physicalId), which every
+        // app-scoped resource carries in `app`.
+        { kind: "Fly::Machines::App", ids: ["app"] },
+        // A Volume is referenced by name; its id is already indexed via physicalId,
+        // so a mount that names either resolves.
+        { kind: "Fly::Machines::Volume", ids: ["volumeName"] },
+    ],
+    refs: [
+        // Containment: everything app-scoped lives inside its App → a boundary box.
+        { from: "Fly::Machines::Machine", path: "app", targetKind: "Fly::Machines::App", relation: "containment", label: "in app" },
+        { from: "Fly::Machines::Volume", path: "app", targetKind: "Fly::Machines::App", relation: "containment", label: "in app" },
+        { from: "Fly::Machines::IPAddress", path: "app", targetKind: "Fly::Machines::App", relation: "containment", label: "in app" },
+        { from: "Fly::Machines::Certificate", path: "app", targetKind: "Fly::Machines::App", relation: "containment", label: "in app" },
+        // Reference edge: a machine mount → the Volume it mounts.
+        { from: "Fly::Machines::Machine", path: "config.mounts[].volume", targetKind: "Fly::Machines::Volume", relation: "reference", label: "mounts" },
+    ],
+};

package/dist/release-metadata.js

@@ -0,0 +1,59 @@
+/**
+ * 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",
+};
+/** The release a Machine's metadata names, or undefined when it names none. Pure. */
+export function readMachineRelease(metadata) {
+    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, release) {
+    const out = structuredClone(config ?? {});
+    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;
+}