@intentius/chant-lexicon-fly 0.16.0 → 0.18.0

package/README.md

@@ -26,9 +26,9 @@ It fits two kinds of user: teams running on Fly who want their infrastructure as
 ## Author infrastructure as typed code
 
 ```ts
-import { App, Machine, MachineConfig, MachineGuest } from "@intentius/chant-lexicon-fly";
+import { App, Machine, MachineConfig, MachineGuest, Fly } from "@intentius/chant-lexicon-fly";
 
-export const app = new App({ name: "my-app" });
+export const app = new App({ name: "my-app", org_slug: Fly.OrgSlug });
 
 export const web = new Machine({
   region: "iad",

package/dist/composites/fly-deploy.d.ts

@@ -32,7 +32,7 @@ export interface FlapsStepOpts {
     name?: string;
     /** Host port mapped to the emulator's `:4280`. Default: `4280`. */
     port?: number;
-    /** Image. Default: `ghcr.io/intentius/mudflaps:0.3.0`. */
+    /** Image. Default: the pinned mudflaps image (`MUDFLAPS_IMAGE`, from the flapsUp activity). */
     image?: string;
     /** Readiness timeout in ms. */
     timeoutMs?: number;

package/dist/composites/fly-deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fly-deploy.d.ts","sourceRoot":"","sources":["../../src/composites/fly-deploy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,oEAAoE;AACpE,eAAO,MAAM,oBAAoB,0BAA0B,CAAC;AAE5D,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,aAAa,KAAG,YAG9C,CAAC;AAEF,kKAAkK;AAClK,eAAO,MAAM,SAAS,GAAI,OAAO,aAAa,KAAG,YAGhD,CAAC;AAEF,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,iCAAiC;IACjC,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,UAAU,MAAM,EAAE,OAAO,gBAAgB,KAAG,YAGxE,CAAC;AAEF,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,aAAkB,GAAG,YAAY,CAAC,OAAO,UAAU,CAAC,CAyCnF"}
+{"version":3,"file":"fly-deploy.d.ts","sourceRoot":"","sources":["../../src/composites/fly-deploy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,oEAAoE;AACpE,eAAO,MAAM,oBAAoB,0BAA0B,CAAC;AAE5D,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,aAAa,KAAG,YAG9C,CAAC;AAEF,kKAAkK;AAClK,eAAO,MAAM,SAAS,GAAI,OAAO,aAAa,KAAG,YAGhD,CAAC;AAEF,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,iCAAiC;IACjC,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,UAAU,MAAM,EAAE,OAAO,gBAAgB,KAAG,YAGxE,CAAC;AAEF,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,aAAkB,GAAG,YAAY,CAAC,OAAO,UAAU,CAAC,CAyCnF"}

package/dist/coverage.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Coverage analysis for the fly lexicon (#804) — how much of the generated
+ * Machines API surface the lexicon's typed resources cover. Thin wrapper over
+ * the shared `computeCoverage`, mirroring the docker/gcp/github peers.
+ */
+import { computeCoverage, overallPct, formatSummary, formatVerbose, checkThresholds, type CoverageReport, type CoverageThresholds } from "@intentius/chant/codegen/coverage";
+export type { CoverageReport, CoverageThresholds };
+export { computeCoverage, overallPct, formatSummary, formatVerbose, checkThresholds };
+/** Run coverage analysis for the fly lexicon. */
+export declare function analyzeFlyCoverage(opts?: {
+    basePath?: string;
+    verbose?: boolean;
+    minOverall?: number;
+}): Promise<CoverageReport>;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../src/coverage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EACL,eAAe,EACf,UAAU,EACV,aAAa,EACb,aAAa,EACb,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,mCAAmC,CAAC;AAE3C,YAAY,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC;AAEtF,iDAAiD;AACjD,wBAAsB,kBAAkB,CAAC,IAAI,CAAC,EAAE;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,cAAc,CAAC,CAqB1B"}

package/dist/emulator-freshness-cli.d.ts

@@ -0,0 +1,11 @@
+/**
+ * CLI for the emulator-freshness check (#808 T2). Fetches the latest mudflaps /
+ * spritzer releases, compares to the pinned tags, prints a report, and — when
+ * run in CI — writes `behind` + a Markdown `body` to `$GITHUB_OUTPUT` so the
+ * weekly workflow can open/refresh a single "N releases behind" notice issue.
+ *
+ * Advisory only: exits 0 whether or not a pin is behind (the bump is a human
+ * decision per the #808 policy). A hard failure (network/API) exits 1.
+ */
+export {};
+//# sourceMappingURL=emulator-freshness-cli.d.ts.map

package/dist/emulator-freshness-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emulator-freshness-cli.d.ts","sourceRoot":"","sources":["../src/emulator-freshness-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/emulator-freshness.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Emulator-freshness check (#808 T2, second half).
+ *
+ * mudflaps (Machines) and spritzer (Sprites) are pinned to a single source
+ * (./op/activities/emulator-images.ts). Their upstream repos cut GitHub releases,
+ * so this compares each pinned tag against the latest release and reports how far
+ * behind it is. A weekly workflow surfaces a "N releases behind" notice — never
+ * an auto-bump. Per the bump policy (#808), the tag moves only when a consuming
+ * test needs the newer emulator, so this is advisory, not gating on the pin.
+ */
+export interface EmulatorPin {
+    /** Short name, e.g. "mudflaps". */
+    name: string;
+    /** GitHub repo "owner/name" whose releases publish the emulator. */
+    repo: string;
+    /** Pinned version, no leading "v" (e.g. "0.3.1"). */
+    pinned: string;
+}
+export interface FreshnessResult {
+    name: string;
+    pinned: string;
+    latest: string;
+    /** True when the latest release is newer than the pinned version. */
+    behind: boolean;
+}
+/** Parse the version tag from a ghcr image ref (".../mudflaps:0.3.1" → "0.3.1"). */
+export declare function parseVersion(image: string): string;
+/** Compare pinned vs latest as dotted numeric versions; `behind` when latest > pinned. */
+export declare function compare(name: string, pinned: string, latest: string): FreshnessResult;
+/** The emulator pins to check, read from the single-source image constants. */
+export declare const EMULATOR_PINS: readonly EmulatorPin[];
+/** Fetch the latest release tag for a repo via the GitHub REST API. */
+export declare function latestRelease(repo: string, fetchImpl?: typeof fetch): Promise<string>;
+/** Check every emulator pin against its latest release. */
+export declare function checkFreshness(fetchImpl?: typeof fetch): Promise<FreshnessResult[]>;
+/** One-line human summary of a result. */
+export declare function formatResult(r: FreshnessResult): string;
+//# sourceMappingURL=emulator-freshness.d.ts.map

package/dist/emulator-freshness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emulator-freshness.d.ts","sourceRoot":"","sources":["../src/emulator-freshness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,WAAW;IAC1B,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGlD;AAMD,0FAA0F;AAC1F,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,CAcrF;AAED,+EAA+E;AAC/E,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAGtC,CAAC;AAEX,uEAAuE;AACvE,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAQlG;AAED,2DAA2D;AAC3D,wBAAsB,cAAc,CAAC,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAIhG;AAED,0CAA0C;AAC1C,wBAAgB,YAAY,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAIvD"}

package/dist/index.d.ts

@@ -4,5 +4,6 @@ export { Fly, Region, OrgSlug, AppName, PseudoParameter } from "./pseudo.js";
 export { FLY_METADATA_OWNERSHIP_KEYS } from "./ownership.js";
 export { flyDeploy, flapsUp, flapsDown, flyApplyStep, LOCAL_FLAPS_ENDPOINT } from "./composites/fly-deploy.js";
 export type { FlyDeployOpts, FlyApplyStepOpts, FlapsStepOpts } from "./composites/fly-deploy.js";
+export { spriteCreate, spriteExec, spriteCheckpoint, spriteRestore, listCheckpoints, spriteDestroy, spritesUp, spritesDown, } from "@intentius/chant/op";
 export * from "./generated/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAGrC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAI7C,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG1E,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAK1D,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC5G,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAK9F,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAGrC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAI7C,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG1E,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAK1D,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC5G,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAM9F,OAAO,EACL,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,aAAa,EACb,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAK7B,cAAc,mBAAmB,CAAC"}

package/dist/mcp/context-tools.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Read-only MCP tools that expose what `chant build` already computes about a
+ * Fly deploy — its apps and machines, the flaps create bodies, image pinning,
+ * and the lexicon's findings — so an agent can ask about a change *before it
+ * runs* (#804).
+ *
+ * Every tool builds from source and returns data. None touch a live Fly org,
+ * read run history, or write anything — the same context-producer boundary the
+ * AWS/GitLab context tools hold.
+ */
+import type { McpToolContribution } from "@intentius/chant/mcp/types";
+/** A container image reference is pinned when it names a digest, not a tag. */
+export declare function imagePinned(image: string): boolean;
+export declare function flyContextTools(): McpToolContribution[];
+//# sourceMappingURL=context-tools.d.ts.map

package/dist/mcp/context-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-tools.d.ts","sourceRoot":"","sources":["../../src/mcp/context-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AA+BtE,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,wBAAgB,eAAe,IAAI,mBAAmB,EAAE,CAoEvD"}

package/dist/op/activities/emulator-images.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Single source of truth for the Fly emulator image pins (#808 T2).
+ *
+ * mudflaps (Machines API) and spritzer (Sprites API) are the local fakes fly's
+ * activities are exercised against. These tags were previously duplicated across
+ * flaps.ts, sprites-emulator.ts, the fly-deploy composite, and tests — and had
+ * already drifted (the composite's docstring said mudflaps 0.3.0 while the
+ * activity pinned 0.3.1). Pin each here so a bump touches one line and the
+ * emulator-freshness check (#808 T2) has a single target to compare against the
+ * latest GHCR release.
+ *
+ * Bump policy (#808): move these only when a consuming test needs a newer
+ * emulator (a fidelity fix the activities exercise), not on every emulator
+ * release. For new upstream API surface the emulator leads, then fly bumps here.
+ */
+/** Pinned mudflaps (Fly Machines / flaps emulator) image. */
+export declare const MUDFLAPS_IMAGE = "ghcr.io/intentius/mudflaps:0.4.0";
+/** Pinned spritzer (Fly Sprites emulator) image. */
+export declare const SPRITZER_IMAGE = "ghcr.io/intentius/spritzer:0.3.1";
+//# sourceMappingURL=emulator-images.d.ts.map

package/dist/op/activities/emulator-images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emulator-images.d.ts","sourceRoot":"","sources":["../../../src/op/activities/emulator-images.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,6DAA6D;AAC7D,eAAO,MAAM,cAAc,qCAAqC,CAAC;AAEjE,oDAAoD;AACpD,eAAO,MAAM,cAAc,qCAAqC,CAAC"}

package/dist/op/activities/flaps.d.ts

@@ -3,7 +3,7 @@ export interface FlapsUpArgs {
     name?: string;
     /** Host port mapped to the emulator's `:4280`. Default: `4280`. */
     port?: number;
-    /** Image. Default: `ghcr.io/intentius/mudflaps:0.3.0`. */
+    /** Image. Default: the pinned mudflaps image ({@link MUDFLAPS_IMAGE}). */
     image?: string;
     /** Readiness timeout in ms. Default: `60000`. */
     timeoutMs?: number;

package/dist/op/activities/flaps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flaps.d.ts","sourceRoot":"","sources":["../../../src/op/activities/flaps.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAYD,eAAO,MAAM,kBAAkB,0BAAsB,CAAC;AACtD,eAAO,MAAM,cAAc,0BAAkB,CAAC;AAC9C,eAAO,MAAM,cAAc,0BAAkB,CAAC;AAC9C,4FAA4F;AAC5F,eAAO,MAAM,aAAa,0BAAiB,CAAC;AAC5C,eAAO,MAAM,eAAe,GAAI,OAAM,WAAgB,KAAG,MAAgC,CAAC;AAE1F,2FAA2F;AAC3F,eAAO,MAAM,OAAO,GAAI,OAAM,WAAgB,EAAE,SAAS,WAAW,KAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAC3E,CAAC;AAEzB,4EAA4E;AAC5E,eAAO,MAAM,SAAS,GAAI,OAAM,aAAkB,EAAE,SAAS,WAAW,KAAG,OAAO,CAAC,IAAI,CAC7D,CAAC"}
+{"version":3,"file":"flaps.d.ts","sourceRoot":"","sources":["../../../src/op/activities/flaps.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAYD,eAAO,MAAM,kBAAkB,0BAAsB,CAAC;AACtD,eAAO,MAAM,cAAc,0BAAkB,CAAC;AAC9C,eAAO,MAAM,cAAc,0BAAkB,CAAC;AAC9C,4FAA4F;AAC5F,eAAO,MAAM,aAAa,0BAAiB,CAAC;AAC5C,eAAO,MAAM,eAAe,GAAI,OAAM,WAAgB,KAAG,MAAgC,CAAC;AAE1F,2FAA2F;AAC3F,eAAO,MAAM,OAAO,GAAI,OAAM,WAAgB,EAAE,SAAS,WAAW,KAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAC3E,CAAC;AAEzB,4EAA4E;AAC5E,eAAO,MAAM,SAAS,GAAI,OAAM,aAAkB,EAAE,SAAS,WAAW,KAAG,OAAO,CAAC,IAAI,CAC7D,CAAC"}

package/dist/op/activities/index.d.ts

@@ -9,4 +9,8 @@ export { flyApply, flyDelete, applyApp, applyMachine, destroyMachine, deleteApp,
 export type { FlyApplyArgs, FlyPlan, FlapsRequest, FlapsMachine, FlyHttp, WaitOpts, ApplyCtx } from "./fly-apply.js";
 export { flapsUp, flapsDown, flapsRunCommand, flapsRmCommand, flapsExistsCommand, flapsHealthUrl, flapsEndpoint, } from "./flaps.js";
 export type { FlapsUpArgs, FlapsDownArgs } from "./flaps.js";
+export { spriteCreate, spriteExec, spriteCheckpoint, spriteRestore, listCheckpoints, spriteDestroy, resolveSpritesEndpoint, defaultSpritesHttp, spriteCreateBody, parseCreateResponse, accumulateExecFrames, parseCheckpointNdjson, pickCheckpointByComment, splitCommand, spriteExecWsUrl, DEFAULT_SPRITES_BASE_URL, } from "./sprites.js";
+export type { SpritesHttp, SpriteCreateArgs, SpriteCreateResult, SpriteExecArgs, SpriteExecResult, SpriteCheckpointArgs, SpriteCheckpointResult, SpriteRestoreArgs, ListCheckpointsArgs, Checkpoint, SpriteDestroyArgs, } from "./sprites.js";
+export { spritesUp, spritesDown, spritesRunCommand, spritesRmCommand, spritesExistsCommand, spritesHealthUrl, spritesEndpoint, } from "./sprites-emulator.js";
+export type { SpritesUpArgs, SpritesDownArgs } from "./sprites-emulator.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/op/activities/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,SAAS,EACT,YAAY,EACZ,aAAa,EACb,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,eAAe,EACf,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIlH,OAAO,EACL,OAAO,EACP,SAAS,EACT,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,SAAS,EACT,YAAY,EACZ,aAAa,EACb,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,eAAe,EACf,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIlH,OAAO,EACL,OAAO,EACP,SAAS,EACT,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAQ1D,OAAO,EACL,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,aAAa,EACb,sBAAsB,EACtB,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,YAAY,EACZ,eAAe,EACf,wBAAwB,GACzB,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,EACnB,UAAU,EACV,iBAAiB,GAClB,MAAM,WAAW,CAAC;AAMnB,OAAO,EACL,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/op/activities/machines-contract.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Fly Machines (flaps) API contract — the endpoint set the `flyApply` applier
+ * (./fly-apply.ts) depends on, and the mudflaps counterpart of the hand-authored
+ * Sprites contract (./sprites-contract.ts, #808 T3).
+ *
+ * Unlike Sprites, Machines *does* ship a machine-readable OpenAPI that the fly
+ * resource surface drift-checks against (docs.machines.dev, the rolling-upgrade
+ * path #813). This contract serves a different fidelity axis: it pins the exact
+ * endpoints flyApply calls so the docker-gated coverage test can prove the pinned
+ * mudflaps emulator serves them all. mudflaps carries roadmap endpoints that
+ * answer 501 (currently machines/{id}/signal, /exec, /ps) — flyApply must never
+ * depend on one; if it ever does, the coverage test fails instead of the applier
+ * silently passing against a fake that can't model the call.
+ *
+ * Param names match ./fly-apply.ts's URL builders (`{app}`, `{id}`); the coverage
+ * check normalizes param names before comparing, since mudflaps spells volume
+ * ids `{vol}` and cert hostnames `{hostname}`.
+ */
+/** One flaps endpoint the flyApply applier calls. */
+export interface MachinesEndpoint {
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    /** Path template under the flaps base, e.g. `/v1/apps/{app}/machines/{id}`. */
+    path: string;
+    /** The applier operation that calls it. */
+    op: string;
+}
+/**
+ * The flaps endpoints ./fly-apply.ts depends on. Keep in sync with the applier —
+ * the unit test asserts every path segment appears in fly-apply.ts.
+ */
+export declare const MACHINES_CONTRACT: readonly MachinesEndpoint[];
+/** Normalize a `METHOD path` key: collapse every `{param}` to `{}` so param names match. */
+export declare function normalizeEndpoint(method: string, path: string): string;
+/** The contract as a set of normalized `METHOD path` keys. */
+export declare function contractKeys(): Set<string>;
+//# sourceMappingURL=machines-contract.d.ts.map

package/dist/op/activities/machines-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"machines-contract.d.ts","sourceRoot":"","sources":["../../../src/op/activities/machines-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,qDAAqD;AACrD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,gBAAgB,EA8B/C,CAAC;AAEX,4FAA4F;AAC5F,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtE;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,IAAI,GAAG,CAAC,MAAM,CAAC,CAE1C"}

package/dist/op/activities/sprites-contract.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Hand-authored Fly Sprites API contract (#808 T3).
+ *
+ * The Fly Machines API ships a machine-readable OpenAPI (docs.machines.dev) that
+ * the fly resource surface generates + drift-checks against. The Sprites API
+ * (api.sprites.dev) ships no such spec at any conventional path, so there is
+ * nothing to diff automatically. This module is the manual stand-in: the exact
+ * endpoint set the fly sprite activities (./sprites.ts) depend on, maintained by
+ * hand from https://docs.sprites.dev.
+ *
+ * It anchors two fidelity checks:
+ *   1. Coverage — every endpoint here must be served by the pinned spritzer
+ *      emulator (its `/_spritzer/health` enumerates implemented paths). If an
+ *      activity ever calls something spritzer doesn't model, the docker-gated
+ *      contract test fails instead of silently passing against a partial fake.
+ *   2. Drift anchor — when the Sprites API changes, a human updates this file;
+ *      reviewers see exactly which activity/endpoint moved.
+ *
+ * Path params are written with names matching ./sprites.ts (`{id}`, `{cp}`);
+ * the coverage check normalizes param names before comparing, since spritzer
+ * spells the checkpoint id `{cid}`.
+ */
+/** One endpoint the fly sprite activities call. */
+export interface SpritesEndpoint {
+    /** HTTP method, or "WS" for the control-WebSocket exec channel. */
+    method: "GET" | "POST" | "DELETE" | "WS";
+    /** Path template under the Sprites base, e.g. `/v1/sprites/{id}/checkpoint`. */
+    path: string;
+    /** The fly activity that calls it (./sprites.ts export). */
+    activity: string;
+}
+/**
+ * The Sprites endpoints ./sprites.ts depends on. Keep in sync with the activity
+ * implementations — the unit test asserts every sprite activity is represented.
+ */
+export declare const SPRITES_CONTRACT: readonly SpritesEndpoint[];
+/**
+ * Normalize a `METHOD path` key for comparison across sources: collapse every
+ * `{param}` to `{}` (so `{cp}` and `{cid}` match) and treat the WebSocket exec
+ * channel as a `GET` (spritzer registers it as `GET .../exec`).
+ */
+export declare function normalizeEndpoint(method: string, path: string): string;
+/** The contract as a set of normalized `METHOD path` keys. */
+export declare function contractKeys(): Set<string>;
+//# sourceMappingURL=sprites-contract.d.ts.map

package/dist/op/activities/sprites-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprites-contract.d.ts","sourceRoot":"","sources":["../../../src/op/activities/sprites-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;IACzC,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,eAAe,EAO7C,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAItE;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,IAAI,GAAG,CAAC,MAAM,CAAC,CAE1C"}

package/dist/op/activities/sprites-emulator.d.ts

@@ -0,0 +1,29 @@
+export interface SpritesUpArgs {
+    /** Container name. Default: `chant-spritzer`. */
+    name?: string;
+    /** Host port mapped to the emulator's `:4290`. Default: `4290`. */
+    port?: number;
+    /** Image. Default: the pinned spritzer image ({@link SPRITZER_IMAGE}). */
+    image?: string;
+    /** Readiness timeout in ms. Default: `60000`. */
+    timeoutMs?: number;
+    /** Health poll interval in ms. Default: `2000`. */
+    intervalMs?: number;
+}
+export interface SpritesDownArgs {
+    /** Container name to remove. Default: `chant-spritzer`. */
+    name?: string;
+}
+export declare const spritesExistsCommand: (name: string) => string;
+export declare const spritesRmCommand: (name: string) => string;
+export declare const spritesHealthUrl: (port: number) => string;
+/** The Sprites endpoint URL (what the sprite activities' `SPRITES_BASE_URL`/`endpoint` points at). */
+export declare const spritesEndpoint: (port: number) => string;
+export declare const spritesRunCommand: (args?: SpritesUpArgs) => string;
+/** Boot a local spritzer (Fly Sprites API emulator) in Docker and return its endpoint. */
+export declare const spritesUp: (args?: SpritesUpArgs, signal?: AbortSignal) => Promise<{
+    endpoint: string;
+}>;
+/** Stop and remove the local spritzer container (no-op if already gone). */
+export declare const spritesDown: (args?: SpritesDownArgs, signal?: AbortSignal) => Promise<void>;
+//# sourceMappingURL=sprites-emulator.d.ts.map

package/dist/op/activities/sprites-emulator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprites-emulator.d.ts","sourceRoot":"","sources":["../../../src/op/activities/sprites-emulator.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAaD,eAAO,MAAM,oBAAoB,0BAAyB,CAAC;AAC3D,eAAO,MAAM,gBAAgB,0BAAqB,CAAC;AACnD,eAAO,MAAM,gBAAgB,0BAAqB,CAAC;AACnD,sGAAsG;AACtG,eAAO,MAAM,eAAe,0BAAoB,CAAC;AACjD,eAAO,MAAM,iBAAiB,GAAI,OAAM,aAAkB,KAAG,MAAmC,CAAC;AAEjG,0FAA0F;AAC1F,eAAO,MAAM,SAAS,GAAI,OAAM,aAAkB,EAAE,SAAS,WAAW,KAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAC5E,CAAC;AAE5B,4EAA4E;AAC5E,eAAO,MAAM,WAAW,GAAI,OAAM,eAAoB,EAAE,SAAS,WAAW,KAAG,OAAO,CAAC,IAAI,CAC9D,CAAC"}

package/dist/op/activities/sprites-fake.d.ts

@@ -0,0 +1,62 @@
+/**
+ * In-process Sprites fake (#762, #766, S7) — a fake of the faithful Sprites API
+ * surface for offline, Docker-free integration tests.
+ *
+ * It models the lifecycle state machine and checkpoint/restore semantics, not
+ * real Firecracker VMs or real code execution (that fidelity is out of scope).
+ * A sprite's filesystem is a `Record<string, string>`; `exec` runs a small
+ * scripted interpreter that can write/modify an `fs` key so checkpoint/restore
+ * is observable; `checkpoint` deep-copies `fs` under a version id; `restore`
+ * replaces `fs` with that copy. Started in-process by a test and reached via
+ * `SPRITES_BASE_URL`, so the same activities that hit real Sprites hit the fake.
+ *
+ * The wire surface matches the released `spritzer:0.3.1` image so the CI
+ * fake-based test and the docker test exercise the same protocol:
+ *  - `exec` over the control WebSocket with `[StreamID][payload]` binary framing;
+ *  - `POST /checkpoint` (singular) returning NDJSON progress + a `complete` event;
+ *  - `GET /checkpoints` returning a bare array of `{ id, comment, create_time, is_auto }`;
+ *  - `POST /checkpoints/{id}/restore` returning NDJSON.
+ * Checkpoint ids are server versions (`v1`, `v2`, ...).
+ */
+type SpriteStatus = "starting" | "running" | "paused" | "destroyed";
+interface StoredCheckpoint {
+    id: string;
+    comment: string;
+    create_time: string;
+    is_auto: boolean;
+    fs: Record<string, string>;
+}
+interface SpriteState {
+    id: string;
+    status: SpriteStatus;
+    url: string;
+    /** Filesystem model: path → contents. */
+    fs: Record<string, string>;
+    /** Checkpoints in creation order; each holds a full copy of `fs` at that time. */
+    checkpoints: StoredCheckpoint[];
+    /** Monotonic version counter for `v<N>` ids. */
+    version: number;
+    policy?: unknown;
+}
+interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * Run one command against a sprite's `fs`. Not a real shell: it recognizes a
+ * small set of forms so a test (and the example `guarded-task` Op) can write a
+ * key, then overwrite/fail it, and prove restore rewinds. Segments split on
+ * `;` run in order; the exit code is the last segment's (shell `;` semantics).
+ */
+export declare function fakeExec(sprite: SpriteState, cmd: string): ExecResult;
+/**
+ * Start the in-process Sprites fake on an ephemeral port. Returns its base
+ * `url` (feed it to `SPRITES_BASE_URL`) and a `close()`.
+ */
+export declare function createSpritesFake(): Promise<{
+    url: string;
+    close(): Promise<void>;
+}>;
+export {};
+//# sourceMappingURL=sprites-fake.d.ts.map

package/dist/op/activities/sprites-fake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprites-fake.d.ts","sourceRoot":"","sources":["../../../src/op/activities/sprites-fake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,KAAK,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEpE,UAAU,gBAAgB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5B;AAED,UAAU,WAAW;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,YAAY,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,kFAAkF;IAClF,WAAW,EAAE,gBAAgB,EAAE,CAAC;IAChC,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAwCrE;AAqCD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CA4KpF"}

package/dist/op/activities/sprites.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Sprites lifecycle activities (#762, #766) — imperative, checkpointable sandbox
+ * primitives ([sprites.dev](https://sprites.dev)) as chant Op activities, wired
+ * to the faithful Sprites API.
+ *
+ * Unlike a resource lexicon, Sprites have no desired state to reconcile: they
+ * are runtime-orchestration primitives (the same category as `k3dUp` /
+ * `httpCheck`). Most activities are a direct call over an injectable HTTP client
+ * (`SpritesHttp`); `spriteExec` is the exception — it speaks the control
+ * WebSocket exec protocol (non-PTY stream framing, per superfly/sprites-go), so
+ * it opens a `ws` connection instead. Exported pure helpers (endpoint
+ * resolution, the exec frame accumulator, NDJSON parsers, the comment picker)
+ * keep the logic unit-testable without a socket or an HTTP server.
+ *
+ * The headline capability is checkpoint-as-compensation (S5): an Op checkpoints
+ * before a risky phase and, on failure, `spriteRestore`s the labeled checkpoint
+ * instead of unwinding with an inverse action — the environment itself is the
+ * transaction.
+ *
+ * S3: endpoint override via `SPRITES_BASE_URL` (an explicit `endpoint` arg wins,
+ * then the env, then the real Sprites base), so the same Op targets real Sprites
+ * or the in-process fake with no code change.
+ */
+export declare const DEFAULT_SPRITES_BASE_URL = "https://api.sprites.dev";
+/**
+ * Resolve the Sprites base URL (S3): an explicit `endpoint` arg wins, then the
+ * `SPRITES_BASE_URL` env, then the real-Sprites default. The trailing slash is
+ * stripped so `${base}/v1/...` never doubles up. Pure — mirrors fly's
+ * `resolveEndpoint`.
+ */
+export declare function resolveSpritesEndpoint(args?: {
+    endpoint?: string;
+}, env?: NodeJS.ProcessEnv): string;
+export declare const STREAM_STDIN = 0;
+export declare const STREAM_STDOUT = 1;
+export declare const STREAM_STDERR = 2;
+export declare const STREAM_EXIT = 3;
+export declare const STREAM_STDIN_EOF = 4;
+/**
+ * Accumulate a stream of exec frames into `{ stdout, stderr, exitCode }`. Pure
+ * and socket-free so the framing is unit-testable: feed `[1]"hi\n"`, `[3]\x00`
+ * and get `{ stdout: "hi\n", exitCode: 0 }`. Per-stream payloads are collected
+ * as bytes and decoded once, so a multi-byte character split across frames is
+ * preserved. The exit code is the first byte of the `[3]` frame (0 when absent).
+ */
+export declare function accumulateExecFrames(frames: Iterable<Uint8Array>): SpriteExecResult;
+/**
+ * Tokenize a command string into an argv, respecting single/double quotes so
+ * `sh -c "exit 7"` becomes `["sh", "-c", "exit 7"]`. Each element is sent as a
+ * `cmd` query param; `path` is `argv[0]`. Pure.
+ */
+export declare function splitCommand(cmd: string): string[];
+/**
+ * Build the `wss://.../exec?cmd=...&path=...&stdin=false&cc=true` URL for a
+ * command (http→ws, https→wss). Pure.
+ */
+export declare function spriteExecWsUrl(base: string, id: string, cmd: string): string;
+/**
+ * Parse a checkpoint create NDJSON body (line-delimited JSON progress events)
+ * and capture the created version id. Real Sprites tags each event with a
+ * `type` and a human `data` string — the version id rides inside the text
+ * ("  ID: v1" and "Checkpoint v1 created successfully"), not a structured
+ * field. The in-process fake mirrors that. An older shape (`{event, id}`) is
+ * still honored so a structured id always wins. Pure; blank/unparseable lines
+ * are skipped; `checkpointId` is "" when the stream carries no id.
+ */
+export declare function parseCheckpointNdjson(text: string): SpriteCheckpointResult;
+/**
+ * Pick the newest checkpoint whose `comment` matches, so a comment-tagged
+ * restore rewinds to the most recent labeled snapshot. Newest is by
+ * `create_time`; array order breaks ties (the list is chronological). Pure.
+ */
+export declare function pickCheckpointByComment(list: Checkpoint[], comment: string): Checkpoint | undefined;
+export interface SpriteCreateArgs {
+    /** Caller-chosen name, used as the sprite `id` (S4). Every later activity keys on it. */
+    name: string;
+    /** Base image for the sandbox. */
+    image?: string;
+    /** Sandbox size (vCPU/memory class). */
+    size?: string;
+    /** Network / execution policy passed through to the sprite. */
+    policy?: unknown;
+    /** Endpoint override (S3). Default: `SPRITES_BASE_URL`, else real Sprites. */
+    endpoint?: string;
+    /** Bearer token. Default: `SPRITES_API_TOKEN`. The fake ignores it. */
+    token?: string;
+}
+export interface SpriteCreateResult {
+    id: string;
+    url: string;
+}
+export interface SpriteExecArgs {
+    /** Target sprite id (the `name` passed to `spriteCreate`). */
+    id: string;
+    /** Command to run inside the sprite (tokenized into argv, quotes respected). */
+    cmd: string;
+    /** Per-exec timeout in ms. */
+    timeoutMs?: number;
+    endpoint?: string;
+    token?: string;
+}
+export interface SpriteExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface SpriteCheckpointArgs {
+    id: string;
+    /** Caller-chosen checkpoint comment (S4); a comment-tagged `spriteRestore` matches it. */
+    comment?: string;
+    endpoint?: string;
+    token?: string;
+}
+export interface SpriteCheckpointResult {
+    /** The server checkpoint version (e.g. `v3`) captured from the `complete` event. */
+    checkpointId: string;
+}
+export interface Checkpoint {
+    id: string;
+    comment: string;
+    create_time: string;
+    is_auto: boolean;
+}
+export interface SpriteRestoreArgs {
+    id: string;
+    /** Explicit checkpoint id (e.g. `v3`); wins over `comment`. */
+    checkpoint?: string;
+    /** Restore the newest checkpoint carrying this comment. */
+    comment?: string;
+    endpoint?: string;
+    token?: string;
+}
+export interface ListCheckpointsArgs {
+    id: string;
+    endpoint?: string;
+    token?: string;
+}
+export interface SpriteDestroyArgs {
+    id: string;
+    endpoint?: string;
+    token?: string;
+}
+/** Build the `POST /v1/sprites` body. Pure. */
+export declare function spriteCreateBody(args: SpriteCreateArgs): Record<string, unknown>;
+/** Parse the create response; the caller-chosen `name` is the id fallback (S4). Pure. */
+export declare function parseCreateResponse(text: string, name: string): SpriteCreateResult;
+/**
+ * Injectable HTTP client — mirrors fly's `FlyHttp`. Tests inject a fake; the
+ * default hits `fetch`. Used by create/destroy/checkpoint/list/restore; exec
+ * goes over the control WebSocket instead.
+ */
+export type SpritesHttp = (method: string, url: string, body?: unknown, headers?: Record<string, string>, signal?: AbortSignal) => Promise<{
+    status: number;
+    text: string;
+}>;
+/**
+ * Default `fetch`-based client. Sends `Authorization: Bearer <token>` when a
+ * token is set (real Sprites); the fake ignores it. The token defaults to
+ * `SPRITES_API_TOKEN` at call time. `fetchImpl` is injectable for tests.
+ */
+export declare function defaultSpritesHttp(token?: string, fetchImpl?: typeof fetch): SpritesHttp;
+/** Create a sprite with the caller-chosen `name` as its id (S4). `POST /v1/sprites`. */
+export declare function spriteCreate(args: SpriteCreateArgs, signal?: AbortSignal, http?: SpritesHttp): Promise<SpriteCreateResult>;
+/**
+ * Run a command in the sprite over the control WebSocket (non-PTY stream
+ * framing, per superfly/sprites-go). Connects to `wss://.../exec`, sends a
+ * single `[4]` (stdin EOF), accumulates stdout/stderr frames, and reads the
+ * exit code from the `[3]` frame. A non-zero exit is a failed activity (it
+ * throws) so a risky step fails its phase and triggers `onFailure`
+ * compensation (S5).
+ */
+export declare function spriteExec(args: SpriteExecArgs, signal?: AbortSignal): Promise<SpriteExecResult>;
+/**
+ * Checkpoint the sprite. `POST /v1/sprites/{id}/checkpoint` (singular); the
+ * `comment` key is omitted when empty. The response is an NDJSON progress
+ * stream; the created version id is mined from the message text (see
+ * `parseCheckpointNdjson`).
+ */
+export declare function spriteCheckpoint(args: SpriteCheckpointArgs, signal?: AbortSignal, http?: SpritesHttp): Promise<SpriteCheckpointResult>;
+/**
+ * List a sprite's checkpoints. `GET /v1/sprites/{id}/checkpoints` → a bare array
+ * `[{ id, comment, create_time, is_auto }]` (auto checkpoints excluded by
+ * default on the server).
+ */
+export declare function listCheckpoints(args: ListCheckpointsArgs, signal?: AbortSignal, http?: SpritesHttp): Promise<Checkpoint[]>;
+/**
+ * Restore the sprite to a checkpoint (S5, the compensation path). Resolution
+ * order: an explicit `checkpoint` id wins; otherwise the newest checkpoint
+ * carrying `comment`; otherwise the newest checkpoint overall. Restore is
+ * `POST /v1/sprites/{id}/checkpoints/{cp}/restore` and returns an NDJSON stream.
+ */
+export declare function spriteRestore(args: SpriteRestoreArgs, signal?: AbortSignal, http?: SpritesHttp): Promise<Record<string, never>>;
+/** Destroy the sprite (idempotent; a 404 means it is already gone). `DELETE /v1/sprites/{id}`. */
+export declare function spriteDestroy(args: SpriteDestroyArgs, signal?: AbortSignal, http?: SpritesHttp): Promise<Record<string, never>>;
+//# sourceMappingURL=sprites.d.ts.map

package/dist/op/activities/sprites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprites.d.ts","sourceRoot":"","sources":["../../../src/op/activities/sprites.ts"],"names":[],"mappings":"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"}

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAkD,MAAM,0BAA0B,CAAC;AAiB9G;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,aAsQvB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAkD,MAAM,0BAA0B,CAAC;AAmB9G;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,aA2RvB,CAAC"}