@intentius/chant-lexicon-fly 0.91.0 → 0.93.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"machines-local.d.ts","sourceRoot":"","sources":["../../../src/op/activities/machines-local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAQH,OAAO,EAA2C,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEzI,kIAAkI;AAClI,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;AAEzH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8GAA8G;IAC9G,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,+FAA+F;IAC/F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qGAAqG;IACrG,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oFAAoF;IACpF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,mBAAmB,CAAC,QAAQ,CAAC,CAAC;CACxC;AAED,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,yEAAyE;IACzE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD,wGAAwG;IACxG,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACxD,iCAAiC;IACjC,SAAS,IAAI,YAAY,EAAE,CAAC;IAC5B,gEAAgE;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAwDD,oGAAoG;AACpG,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,oBAAyB,GAAG,aAAa,CAqOrF;AAED,MAAM,WAAW,yBAA0B,SAAQ,oBAAoB;IACrE,8FAA8F;IAC9F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,aAAa,CAAC;IACxB,qDAAqD;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,yBAA8B,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAiC9G"}

package/dist/op/activities/sprite-fs.d.ts

@@ -8,8 +8,12 @@
  * read/write move raw file bytes in the body (not JSON), so these use a small
  * raw HTTP client (`SpritesRawHttp`) rather than the JSON `SpritesHttp` the
  * lifecycle activities use; path/mode/mkdir/recursive ride as query params.
- * Endpoint + bearer resolution mirror `sprites.ts` — an explicit `endpoint` /
- * `token` wins, then `SPRITES_BASE_URL` / `SPRITES_API_TOKEN`.
+ * Endpoint + bearer resolution go through `sprites.ts`'s shared resolvers
+ * (`resolveSpritesEndpoint`/`resolveSpritesToken`) — an explicit `endpoint` /
+ * `token` wins, then `SPRITES_BASE_URL`/`SPRITES_API_URL`, then
+ * `SPRITES_API_TOKEN`/its `SPRITE_TOKEN` alias (#2711, #2765: this module
+ * used to read `SPRITES_API_TOKEN` directly, missing the alias the other
+ * Sprites activities honor).
  */
 /**
  * Build a `/v1/sprites/{id}/fs/{op}?...` URL. `params` values that are undefined
@@ -29,7 +33,12 @@ export type SpritesRawHttp = (method: string, url: string, body?: string, header
  * Default `fetch`-based raw client. Sends the body as-is with an
  * `application/octet-stream` content-type and `Authorization: Bearer <token>`
  * when a token is set (real Sprites); the fake ignores the token. The token
- * defaults to `SPRITES_API_TOKEN` at call time. `fetchImpl` is injectable.
+ * resolves through `resolveSpritesToken` at call time — `SPRITES_API_TOKEN`,
+ * then its `SPRITE_TOKEN` alias (#2711, #2765) — the same resolver
+ * `sprites.ts`'s `defaultSpritesHttp` uses, so every fs activity
+ * (`spriteWriteFile`, `spriteReadFile`, `spriteListDir`, `spriteRemove`)
+ * authenticates the same way the lifecycle activities do. `fetchImpl` is
+ * injectable.
  */
 export declare function defaultSpritesRawHttp(token?: string, fetchImpl?: typeof fetch): SpritesRawHttp;
 export interface SpriteWriteFileArgs {

package/dist/op/activities/sprite-fs.d.ts.map

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

package/dist/op/activities/sprite-service-converge.d.ts

@@ -0,0 +1,107 @@
+/**
+ * A sprite's services as resources a `ConvergeOp` observes and converges
+ * (#2778).
+ *
+ * A box runs its app, hud, door and site as services a supervisor keeps
+ * running: sprite-env on a sprite, and a stand-in with the same command line
+ * elsewhere. No lexicon declares them, so a ConvergeOp can't observe them
+ * through an environment. It can through an observer step:
+ *
+ * - `spriteServicesObserve` reads the supervisor's list and probes each
+ *   declared service's health URL, and returns one verdict per service,
+ *   `in-sync`, `drifted` or `unknown`: the `ResourceObservation` a
+ *   `ConvergeOp({ observe })` evaluates its rules against, once per service.
+ * - `spriteServiceRestart` restarts one service through the supervisor and
+ *   waits for its health URL. It is the step of the Op a rule dispatches; the
+ *   service is the one the rule fired for, which the dispatched run reads
+ *   from `CHANT_CONVERGE_RESOURCE`.
+ *
+ * Both work in one of two ways. With no sprite `id`, they run inside the
+ * sprite and call `sprite-env services` (found on PATH or in /.sprite/bin,
+ * or at `spriteEnv`). With an `id`, they go through the Sprites API
+ * (`spriteServiceList`, `spriteServiceStop` and `spriteServiceStart`).
+ */
+import type { SpritesHttp } from "./sprites.js";
+/** One service a box declares. */
+export interface DeclaredSpriteService {
+    name: string;
+    /** A URL that answers 200 while the service works. Without one, the supervisor's state decides. */
+    health?: string;
+    /** Not defined yet is not drift: the service is left out until it exists (a site before its first release). */
+    optional?: boolean;
+}
+interface Via {
+    /** The sprite, for the Sprites API. Without it, `sprite-env` inside the sprite. */
+    id?: string;
+    /** The `sprite-env` binary. Default: the one on PATH, else /.sprite/bin/sprite-env. */
+    spriteEnv?: string;
+    endpoint?: string;
+    token?: string;
+}
+export interface SpriteServicesObserveArgs extends Via {
+    /** The declared services. */
+    services?: DeclaredSpriteService[];
+    /** A JSON file of `{ services: [...] }`, relative to the working directory, read on each tick. */
+    servicesFile?: string;
+    /** Health probes before a service counts as drifted. Default 3. */
+    probes?: number;
+    /** Time between probes, ms. Default 1000. */
+    probeIntervalMs?: number;
+}
+export interface SpriteServicesObserveResult {
+    resources: {
+        name: string;
+        status: "in-sync" | "drifted" | "unknown";
+        detail: string;
+    }[];
+    /** Optional services that aren't defined yet. */
+    skipped: string[];
+}
+export interface SpriteServiceRestartArgs extends Via {
+    /** The service. Default: the resource a ConvergeOp dispatched this run for (`CHANT_CONVERGE_RESOURCE`). */
+    name?: string;
+    /** Its health URL. Default: the one `services` or `servicesFile` declares for it. */
+    health?: string;
+    services?: DeclaredSpriteService[];
+    servicesFile?: string;
+    /** How long to wait for the health URL after the restart, ms. Default 60000. */
+    waitMs?: number;
+}
+export interface SpriteServiceRestartResult {
+    name: string;
+    /** Whether its health URL answered, or null when it declares none. */
+    healthy: boolean | null;
+}
+/** The services declared inline and in `servicesFile`, inline first. */
+export declare function declaredServices(args: {
+    services?: DeclaredSpriteService[];
+    servicesFile?: string;
+}, cwd?: string): DeclaredSpriteService[];
+/** The sprite-env binary, or null when there is none. */
+export declare function findSpriteEnv(explicit?: string, env?: NodeJS.ProcessEnv): string | null;
+/**
+ * `sprite-env services list` as name to state. A sprite's sprite-env prints
+ * JSON (an array of services with `state.status`); a stand-in may print a
+ * tab-separated table whose second column is the state. Pure.
+ */
+export declare function parseServicesList(text: string): Map<string, string | null>;
+/** One GET of a health URL: true on 200. */
+export declare function probeHealth(url: string, signal?: AbortSignal): Promise<boolean>;
+/**
+ * Observe the declared services: one verdict each, for a ConvergeOp's rules.
+ * A service the supervisor doesn't have, or has stopped, is drifted; one
+ * with a health URL is in sync when the URL answers 200 within `probes`
+ * tries and drifted when it doesn't; one without is in sync while it runs.
+ * When the supervisor can't be read, every service is unknown, and unknown
+ * never remediates.
+ */
+export declare function spriteServicesObserve(args: SpriteServicesObserveArgs, signal?: AbortSignal, http?: SpritesHttp): Promise<SpriteServicesObserveResult>;
+/**
+ * Restart one service through its supervisor and wait for its health URL.
+ * The service is `name`, or the resource the ConvergeOp's rule fired for.
+ * Throws when neither names one, when the supervisor refuses, or when the
+ * service does not answer its health URL within `waitMs`.
+ */
+export declare function spriteServiceRestart(args: SpriteServiceRestartArgs, signal?: AbortSignal, http?: SpritesHttp): Promise<SpriteServiceRestartResult>;
+export {};
+//# sourceMappingURL=sprite-service-converge.d.ts.map

package/dist/op/activities/sprite-service-converge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprite-service-converge.d.ts","sourceRoot":"","sources":["../../../src/op/activities/sprite-service-converge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAOH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAY7C,kCAAkC;AAClC,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,mGAAmG;IACnG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+GAA+G;IAC/G,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,UAAU,GAAG;IACX,mFAAmF;IACnF,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,yBAA0B,SAAQ,GAAG;IACpD,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,qBAAqB,EAAE,CAAC;IACnC,kGAAkG;IAClG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACzF,iDAAiD;IACjD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,wBAAyB,SAAQ,GAAG;IACnD,2GAA2G;IAC3G,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,qBAAqB,EAAE,CAAC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;CACzB;AAID,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,QAAQ,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,SAAgB,GAAG,qBAAqB,EAAE,CAWlJ;AAED,yDAAyD;AACzD,wBAAgB,aAAa,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,IAAI,CAMpG;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAoB1E;AAaD,4CAA4C;AAC5C,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CASrF;AAID;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,yBAAyB,EAC/B,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,2BAA2B,CAAC,CAgDtC;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,wBAAwB,EAC9B,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,CAAC,EAAE,WAAW,GACjB,OAAO,CAAC,0BAA0B,CAAC,CAyBrC"}

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

@@ -73,14 +73,31 @@ interface ExecResult {
     stdout: string;
     stderr: string;
     exitCode: number;
+    /**
+     * Fake-only timing hook (#2765): how long `runExec` should hold the frames
+     * before sending them, set by the `sleep` form below. Lets a test prove
+     * `spriteExec`'s `timeoutMs` fires without a slow real exec.
+     */
+    delayMs?: 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).
+ *
+ * `opts.env`/`opts.dir` (#2765) are the `env`/`dir` exec options after they
+ * cross the wire (`env` as `KEY=VALUE` strings, mirroring what the query
+ * params carry) — `env` and `pwd` below echo them back so a test can prove
+ * they reached the command. Real spritzer only wires `env`/`dir` through in
+ * container exec mode (real processes); its interpreter mode — what
+ * `fakeExec` otherwise mirrors — has no notion of either, so this pair of
+ * forms is fake-only, proven separately from the container-mode docker test.
  */
-export declare function fakeExec(sprite: SpriteState, cmd: string): ExecResult;
+export declare function fakeExec(sprite: SpriteState, cmd: string, opts?: {
+    env?: string[];
+    dir?: string;
+}): ExecResult;
 /**
  * Immediate children of `dir` in a flat `path → contents` map: a key
  * `${dir}/name` is a file; `${dir}/name/...` contributes the dir `name` once.

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

@@ -1 +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,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1F;qFACiF;IACjF,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;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;IACjB,0EAA0E;IAC1E,SAAS,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;CACnE;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,CA6CrE;AA4CD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBjI;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CA6WpF"}
+{"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,aAAa;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1F;qFACiF;IACjF,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;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;IACjB,0EAA0E;IAC1E,SAAS,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC,CAAC;CACnE;AAED,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC1C,UAAU,CA2DZ;AA4CD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgBjI;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAwXpF"}

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

@@ -64,10 +64,17 @@ export declare function accumulateExecFrames(frames: Iterable<Uint8Array>): Spri
  */
 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.
+ * Build the `wss://.../exec?cmd=...&path=...&stdin=false&cc=true[&dir=...][&env=K=V]*`
+ * URL for a command (http→ws, https→wss). `dir` and `env` (#2765) are sent the
+ * way wisp's and spritzer's real exec API take them: `dir` is a single query
+ * param, and each `env` entry is its own repeated `env=KEY=VALUE` param — see
+ * wisp's `optsFromValues` (`Dir: q.Get("dir")`, `Env: q["env"]`) and spritzer's
+ * container-mode wrapping (`--dir`/`--env` per `real.go`). Pure.
  */
-export declare function spriteExecWsUrl(base: string, id: string, cmd: string): string;
+export declare function spriteExecWsUrl(base: string, id: string, cmd: string, opts?: {
+    env?: Record<string, string>;
+    dir?: 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
@@ -107,8 +114,16 @@ export interface SpriteExecArgs {
     id: string;
     /** Command to run inside the sprite (tokenized into argv, quotes respected). */
     cmd: string;
-    /** Per-exec timeout in ms. */
+    /**
+     * Per-exec timeout in ms (#2765). When it elapses before the command exits,
+     * the exec WebSocket is aborted and the activity throws a timeout error —
+     * previously declared and never enforced.
+     */
     timeoutMs?: number;
+    /** Extra environment variables for the command, on top of the sprite's own (#2765). */
+    env?: Record<string, string>;
+    /** Working directory to run the command in (#2765). */
+    dir?: string;
     endpoint?: string;
     token?: string;
 }
@@ -176,11 +191,16 @@ export declare function defaultSpritesHttp(token?: string, fetchImpl?: typeof fe
 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).
+ * framing, per superfly/sprites-go). Connects to `wss://.../exec` (`dir`/`env`
+ * riding on the URL — #2765), sends a single `[4]` (stdin EOF), accumulates
+ * stdout/stderr frames, and reads the exit code from the `[3]` frame. A
+ * non-zero exit is a failed activity (it throws) so a risky step fails its
+ * phase and triggers `onFailure` compensation (S5).
+ *
+ * `timeoutMs` (#2765) bounds the whole exec: a timer set at connect time
+ * terminates the WebSocket and rejects with a timeout error once it elapses
+ * without the command finishing. Previously declared on `SpriteExecArgs` and
+ * never read.
  */
 export declare function spriteExec(args: SpriteExecArgs, signal?: AbortSignal): Promise<SpriteExecResult>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"sprites.d.ts","sourceRoot":"","sources":["../../../src/op/activities/sprites.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AASH,eAAO,MAAM,wBAAwB,4BAA4B,CAAC;AAIlE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,EAChC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAGR;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,GAAE,MAAM,GAAG,SAAqB,EACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CAEpB;AAwBD,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,eAAO,MAAM,aAAa,IAAI,CAAC;AAC/B,eAAO,MAAM,aAAa,IAAI,CAAC;AAC/B,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAUlC;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,gBAAgB,CAkBnF;AAQD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAoClD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAS7E;AAID;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,sBAAsB,CAwB1E;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAEnG;AAmBD,MAAM,WAAW,gBAAgB;IAC/B,yFAAyF;IACzF,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,cAAc;IAC7B,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,oFAAoF;IACpF,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,+CAA+C;AAC/C,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOhF;AAED,yFAAyF;AACzF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAGlF;AAID;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAChC,MAAM,CAAC,EAAE,WAAW,KACjB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE/C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,WAAW,CAc/F;AAID,wFAAwF;AACxF,wBAAsB,YAAY,CAChC,IAAI,EAAE,gBAAgB,EACtB,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,GAAE,WAA4C,GACjD,OAAO,CAAC,kBAAkB,CAAC,CAO7B;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuDtG;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,oBAAoB,EAC1B,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,GAAE,WAA4C,GACjD,OAAO,CAAC,sBAAsB,CAAC,CAQjC;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,mBAAmB,EACzB,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,GAAE,WAA4C,GACjD,OAAO,CAAC,UAAU,EAAE,CAAC,CAMvB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,iBAAiB,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,GAAE,WAA4C,GACjD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAmBhC;AAED,kGAAkG;AAClG,wBAAsB,aAAa,CACjC,IAAI,EAAE,iBAAiB,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,GAAE,WAA4C,GACjD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAQhC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,sBAAgB,CAAC;AAC1C,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;AAEjD,MAAM,WAAW,aAAa;IAC5B,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,aAAa,EACnB,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,GAAE,WAA4C,GACjD,OAAO,CAAC,eAAe,CAAC,CAgC1B"}
+{"version":3,"file":"sprites.d.ts","sourceRoot":"","sources":["../../../src/op/activities/sprites.ts"],"names":[],"mappings":"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"}

package/dist/op/activity-contracts.d.ts

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

package/dist/op/activity-contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-contracts.d.ts","sourceRoot":"","sources":["../../src/op/activity-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAmBH,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;EAazC,CAAC;AAEF,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;EAWxC,CAAC"}

package/dist/op/builders.d.ts

@@ -31,9 +31,12 @@ import type { SpriteCreateArgs, SpriteExecArgs, SpriteCheckpointArgs, SpriteRest
 import type { SpriteWriteFileArgs, SpriteReadFileArgs, SpriteListDirArgs, SpriteRemoveArgs } from "./activities/sprite-fs.js";
 import type { SpriteApplyNetworkPolicyArgs, SpriteApplyServicesArgs } from "./activities/sprite-config.js";
 import type { SpriteServiceCreateArgs, SpriteServiceGetArgs, SpriteServiceListArgs, SpriteServiceStartArgs, SpriteServiceStopArgs, SpriteServiceDeleteArgs, SpriteServiceLogsArgs } from "./activities/sprite-services.js";
+import type { SpriteServicesObserveArgs, SpriteServiceRestartArgs } from "./activities/sprite-service-converge.js";
 import type { SpriteTaskCreateArgs, SpriteTaskRefreshArgs, SpriteTaskReleaseArgs } from "./activities/sprite-tasks.js";
 import type { SpritesUpArgs, SpritesDownArgs } from "./activities/sprites-emulator.js";
 import type { FlyMachineReleaseArgs, FlyMachineExecArgs, FlyMachineStateArgs, FlyMachineVerifyArgs, FlyMachineRestoreArgs } from "./activities/machine-release.js";
+import type { FlyReleaseArgs } from "./activities/fly-release-step.js";
+import type { FlyRollbackArgs } from "./activities/fly-rollback-step.js";
 type StepOpts = {
     profile?: ActivityStep["profile"];
 };
@@ -79,6 +82,19 @@ export declare const spriteServiceStop: (args: WithStepRefs<SpriteServiceStopArg
 export declare const spriteServiceDelete: (args: WithStepRefs<SpriteServiceDeleteArgs> & StepOpts) => NamedActivityStep;
 /** Read a background service's log tail (#2711). Defaults to the `fastIdempotent` profile. */
 export declare const spriteServiceLogs: (args: WithStepRefs<SpriteServiceLogsArgs> & StepOpts) => NamedActivityStep;
+/**
+ * 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 declare const spriteServicesObserve: (args: WithStepRefs<SpriteServicesObserveArgs> & StepOpts) => NamedActivityStep;
+/**
+ * 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 declare const spriteServiceRestart: (args: WithStepRefs<SpriteServiceRestartArgs> & StepOpts) => NamedActivityStep;
 /** Create a keep-alive task — the fully typed twin of core's `spriteTaskCreate`. Defaults to the `fastIdempotent` profile. */
 export declare const spriteTaskCreate: (args: WithStepRefs<SpriteTaskCreateArgs> & StepOpts) => NamedActivityStep;
 /** Refresh a keep-alive task's expiry — the fully typed twin of core's `spriteTaskRefresh`. Defaults to the `fastIdempotent` profile. */
@@ -101,5 +117,21 @@ export declare const flyMachineStop: (args: WithStepRefs<FlyMachineStateArgs> &
 export declare const flyMachineVerify: (args: WithStepRefs<FlyMachineVerifyArgs> & StepOpts) => NamedActivityStep;
 /** Put a recorded Machine config back (restore, rollback). Defaults to the `longInfra` profile. */
 export declare const flyMachineRestore: (args: WithStepRefs<FlyMachineRestoreArgs> & StepOpts) => NamedActivityStep;
+/**
+ * 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 declare const flyRelease: (args: WithStepRefs<FlyReleaseArgs> & StepOpts) => NamedActivityStep;
+/**
+ * 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 declare const flyRollback: (args: WithStepRefs<FlyRollbackArgs> & StepOpts) => NamedActivityStep;
 export {};
 //# sourceMappingURL=builders.d.ts.map

package/dist/op/builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/op/builders.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/op/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAY,KAAK,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC1F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,iBAAiB,EAAoB,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC/L,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC3H,OAAO,KAAK,EAAE,4BAA4B,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACxG,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,qBAAqB,EACtB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAChH,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACpH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACpF,OAAO,KAAK,EACV,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEtE,KAAK,QAAQ,GAAG;IAAE,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAA;CAAE,CAAC;AA6BtD,4GAA4G;AAC5G,eAAO,MAAM,YAAY,uDAPuB,iBAOqC,CAAC;AACtF,oHAAoH;AACpH,eAAO,MAAM,UAAU,qDATyB,iBAS+B,CAAC;AAChF,oHAAoH;AACpH,eAAO,MAAM,gBAAgB,2DAXmB,iBAWiD,CAAC;AAClG,8GAA8G;AAC9G,eAAO,MAAM,aAAa,wDAbsB,iBAawC,CAAC;AACzF,gIAAgI;AAChI,eAAO,MAAM,eAAe,0DAfoB,iBAemD,CAAC;AACpG,mHAAmH;AACnH,eAAO,MAAM,aAAa,wDAjBsB,iBAiB6C,CAAC;AAC9F,mGAAmG;AACnG,eAAO,MAAM,YAAY,wDAnBuB,iBAmB0C,CAAC;AAC3F,+HAA+H;AAC/H,eAAO,MAAM,SAAS,oDArB0B,iBAqBiC,CAAC;AAClF,+HAA+H;AAC/H,eAAO,MAAM,eAAe,0DAvBoB,iBAuBmD,CAAC;AACpG,6HAA6H;AAC7H,eAAO,MAAM,cAAc,yDAzBqB,iBAyBgD,CAAC;AACjG,+HAA+H;AAC/H,eAAO,MAAM,aAAa,wDA3BsB,iBA2B6C,CAAC;AAC9F,2HAA2H;AAC3H,eAAO,MAAM,YAAY,uDA7BuB,iBA6B0C,CAAC;AAC3F,0JAA0J;AAC1J,eAAO,MAAM,wBAAwB,mEA/BW,iBA+B8E,CAAC;AAC/H,iJAAiJ;AACjJ,eAAO,MAAM,mBAAmB,8DAjCgB,iBAiC+D,CAAC;AAChH,iMAAiM;AACjM,eAAO,MAAM,mBAAmB,8DAnCgB,iBAmC0D,CAAC;AAC3G,gHAAgH;AAChH,eAAO,MAAM,gBAAgB,2DArCmB,iBAqCsD,CAAC;AACvG,6FAA6F;AAC7F,eAAO,MAAM,iBAAiB,4DAvCkB,iBAuCyD,CAAC;AAC1G,+GAA+G;AAC/G,eAAO,MAAM,kBAAkB,6DAzCiB,iBAyCuD,CAAC;AACxG,2FAA2F;AAC3F,eAAO,MAAM,iBAAiB,4DA3CkB,iBA2CyD,CAAC;AAC1G,iGAAiG;AACjG,eAAO,MAAM,mBAAmB,8DA7CgB,iBA6C+D,CAAC;AAChH,8FAA8F;AAC9F,eAAO,MAAM,iBAAiB,4DA/CkB,iBA+CyD,CAAC;AAC1G;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,gEAtDc,iBAsDqE,CAAC;AACtH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,+DA5De,iBA4D6D,CAAC;AAC9G,8HAA8H;AAC9H,eAAO,MAAM,gBAAgB,2DA9DmB,iBA8DsD,CAAC;AACvG,yIAAyI;AACzI,eAAO,MAAM,iBAAiB,4DAhEkB,iBAgEyD,CAAC;AAC1G,gIAAgI;AAChI,eAAO,MAAM,iBAAiB,4DAlEkB,iBAkEyD,CAAC;AAE1G,0IAA0I;AAC1I,eAAO,MAAM,SAAS,GAAI,OAAM,YAAY,CAAC,aAAa,CAAC,GAAG,QAAa,KAAG,iBACnB,CAAC;AAC5D,6IAA6I;AAC7I,eAAO,MAAM,WAAW,GAAI,OAAM,YAAY,CAAC,eAAe,CAAC,GAAG,QAAa,KAAG,iBACd,CAAC;AAOrE,qIAAqI;AACrI,eAAO,MAAM,iBAAiB,4DAjFkB,iBAiFoD,CAAC;AACrG,2IAA2I;AAC3I,eAAO,MAAM,cAAc,yDAnFqB,iBAmF4C,CAAC;AAC7F,0GAA0G;AAC1G,eAAO,MAAM,iBAAiB,0DArFkB,iBAqFkD,CAAC;AACnG,yEAAyE;AACzE,eAAO,MAAM,cAAc,0DAvFqB,iBAuF4C,CAAC;AAC7F,uHAAuH;AACvH,eAAO,MAAM,gBAAgB,2DAzFmB,iBAyFiD,CAAC;AAClG,mGAAmG;AACnG,eAAO,MAAM,iBAAiB,4DA3FkB,iBA2FoD,CAAC;AACrG;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,qDAnGyB,iBAmG+B,CAAC;AAChF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,sDA3GwB,iBA2GkC,CAAC"}

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

@@ -86,3 +86,70 @@ The step's output carries `uri` and `digest`, so `chant run --components web --e
 Each release's Machine config is kept on `chant/lifecycle` at `<env>/fly/<app>/<machine>/<digest>.json`. `fly-rollback` puts back the config of the release the serving one replaced (or the digest given as `to`), checks it, and outputs that digest so the ledger records it again. `fly-release`'s own saga compensation does the same.
 
 The steps are also Op activities, for an Op that composes them itself: `flyMachineRelease`, `flyMachineExec`, `flyMachineRestart`, `flyMachineStop`, `flyMachineVerify` and `flyMachineRestore`. Wrap a migration's `flyMachineExec` in `effect()` so it fires once.
+
+### A source tree instead of an image
+
+An app with no image of its own ships as its files on the declared runtime image. Give `fly-release` a `source` in place of `image`: an archive made by core's `sourceArchive` step (`git archive` of one directory of a commit, the same bytes for the same commit), the sha256 it must have, the directory it holds, where the files go (default `/srv/app`) and the command that starts the app there. The archive is read only once its bytes hash to that digest, before the Machine changes, so the Machine never gets a tree nobody approved. The files go into the Machine's config, up to 1 MiB base64. A larger app needs an image.
+
+An Op runs the same steps with the `flyRelease` activity, which takes the environment it ships to as `environment` (`env` stays the Machine's env vars). A release Op gates on the plan core's `releasePlan` writes and records the release with `releaseRecord`:
+
+```ts
+import { Op, phase, gate, build, sourceArchive, releasePlan, releaseRecord } from "@intentius/chant/op";
+import { flyRelease } from "@intentius/chant-lexicon-fly";
+
+const archive = sourceArchive("../app", { id: "archive" });
+const plan = releasePlan({ id: "plan", component: "app", env: "fly", gitSha: archive.out.commit, content: { artifact: { digest: archive.out.digest } } });
+
+export default Op({
+  name: "release",
+  overview: "Ship the app member to Fly once its plan is approved",
+  phases: [
+    phase("Build", [archive, build(".", { script: "build:fly" })]),
+    phase("Plan", [plan]),
+    phase("Gate", [gate("ship", { plan: plan.out.digest })]),
+    phase("Ship", [
+      flyRelease({
+        environment: "fly",
+        plan: "dist/fly.json",
+        digest: plan.out.digest,
+        gitSha: archive.out.commit,
+        source: { archive: archive.out.archive, digest: archive.out.digest, dir: archive.out.dir, start: "node server.js" },
+      }),
+    ]),
+    phase("Record", [releaseRecord({ plan: plan.out.file, digest: plan.out.digest, approval: { op: "release", gate: "ship" } })]),
+  ],
+});
+```
+
+The Machine's metadata names the plan's digest, and so does the ledger record, so `chant components status fly --live` reconciles them. Running the Op again for the same commit plans the same digest, leaves the Machine as it is, and records nothing twice.
+
+### Rolling a source release back
+
+A rollback Op takes the site back to the release it served before the latest one. Core's `releaseRollbackPlan` reads the release ledger, reads the earlier release's plan back, archives the same directory of the same commit again, and refuses unless the archive hashes to the digest that plan recorded. The gate binds to the rollback plan's digest. `flyRollback` puts back the Machine config `flyRelease` recorded for that release. It checks the archive against its digest before any flaps call, and checks that the recorded config carries exactly that tree. `releaseRollbackRecord` appends the restored release with `restores`, the actor and the approver:
+
+```ts
+import { Op, phase, gate, build, releaseRollbackPlan, releaseRollbackRecord } from "@intentius/chant/op";
+import { flyRollback } from "@intentius/chant-lexicon-fly";
+
+const plan = releaseRollbackPlan({ id: "plan", component: "app", env: "fly" });
+
+export default Op({
+  name: "rollback",
+  overview: "Put the previous release back on Fly once the rollback plan is approved",
+  phases: [
+    phase("Plan", [plan, build(".", { script: "build:fly" })]),
+    phase("Gate", [gate("rollback", { plan: plan.out.digest })]),
+    phase("Roll back", [
+      flyRollback({
+        environment: "fly",
+        plan: "dist/fly.json",
+        to: plan.out.to,
+        source: { archive: plan.out.archive, digest: plan.out.archiveDigest, dir: plan.out.dir },
+      }),
+    ]),
+    phase("Record", [releaseRollbackRecord({ plan: plan.out.file, digest: plan.out.digest, approval: { op: "rollback", gate: "rollback" } })]),
+  ],
+});
+```
+
+A rollback's own ledger record is not counted as a release, so running the Op again plans the same rollback, leaves the Machine as it is and records nothing. `to: "sha256:..."` on `releaseRollbackPlan` picks another release. Migrations are not undone.

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-fly",
-  "version": "0.91.0",
+  "version": "0.93.0",
   "type": "module",
   "files": [
     "src/",
@@ -35,6 +35,11 @@
       "types": "./dist/op/activities/index.d.ts",
       "default": "./src/op/activities/index.ts"
     },
+    "./op/activity-contracts": {
+      "development": "./src/op/activity-contracts.ts",
+      "types": "./dist/op/activity-contracts.d.ts",
+      "default": "./src/op/activity-contracts.ts"
+    },
     "./lint/post-synth": {
       "development": "./src/lint/post-synth/index.ts",
       "types": "./dist/lint/post-synth/index.d.ts",
@@ -60,11 +65,13 @@
     "@intentius/chant": "*",
     "@types/ws": "^8.5.12",
     "tsc-alias": "^1.8.17",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.91.0",
-    "typescript": "^5.9.3"
+    "@intentius/chant": "^0.93.0",
+    "typescript": "^5.9.3",
+    "zod": "^4.3.6"
   },
   "description": "Fly.io Machines lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",