@intentius/chant-lexicon-fly 0.124.30 → 0.124.32

package/dist/op/activities/sprite-service-converge.js

@@ -0,0 +1,224 @@
+/**
+ * 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`).
+ *
+ * The declared services come from `services`, from a `servicesFile`, or,
+ * with `box: true`, from the `services` of the box block of the workspace
+ * member whose directory holds the working directory (#2880), the list
+ * `chant workspace status --json` prints as `members[].box.services`.
+ */
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { boxServices } from "./box-services.js";
+import { spriteServiceList, spriteServiceStart, spriteServiceStop } from "./sprite-services.js";
+import { defaultSpritesHttp } from "./sprites.js";
+import { logProgress } from "./progress.js";
+const execFileAsync = promisify(execFile);
+/**
+ * The variable a ConvergeOp's dispatched run reads its resource from
+ * (core's `CONVERGE_RESOURCE_ENV`). Spelled out here so the lexicon runs
+ * against a core that predates the export.
+ */
+const CONVERGE_RESOURCE_ENV = "CHANT_CONVERGE_RESOURCE";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** The services declared inline and in `servicesFile`, inline first. */
+export function declaredServices(args, cwd = process.cwd()) {
+    const out = [...(args.services ?? [])];
+    if (args.servicesFile) {
+        const parsed = JSON.parse(readFileSync(resolve(cwd, args.servicesFile), "utf8"));
+        if (!Array.isArray(parsed.services))
+            throw new Error(`${args.servicesFile} has no "services" array`);
+        for (const s of parsed.services) {
+            if (!s || typeof s.name !== "string")
+                throw new Error(`${args.servicesFile}: a service has no name`);
+            out.push(s);
+        }
+    }
+    return out;
+}
+/**
+ * The declared services: with `box: true`, the box block's (#2880), and
+ * otherwise those of {@link declaredServices}. `box` in place of the other
+ * two, never beside them.
+ */
+export async function resolveDeclaredServices(args, cwd = process.cwd()) {
+    if (!args.box)
+        return declaredServices(args, cwd);
+    if (args.services || args.servicesFile)
+        throw new Error("box: true reads the services from the box block, so it takes no services or servicesFile beside it");
+    return (await boxServices(cwd)).map((s) => ({ name: s.name, ...(s.health ? { health: s.health } : {}), ...(s.optional ? { optional: true } : {}) }));
+}
+/** The sprite-env binary, or null when there is none. */
+export function findSpriteEnv(explicit, env = process.env) {
+    if (explicit)
+        return explicit;
+    for (const dir of (env.PATH ?? "").split(":").concat("/.sprite/bin")) {
+        if (dir && existsSync(join(dir, "sprite-env")))
+            return join(dir, "sprite-env");
+    }
+    return 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 function parseServicesList(text) {
+    const out = new Map();
+    const trimmed = text.trim();
+    if (!trimmed)
+        return out;
+    if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+        const parsed = JSON.parse(trimmed);
+        const list = Array.isArray(parsed) ? parsed : (parsed.services ?? []);
+        for (const s of list) {
+            if (typeof s?.name !== "string")
+                continue;
+            const status = typeof s.state?.status === "string" ? s.state.status : typeof s.status === "string" ? s.status : null;
+            out.set(s.name, status);
+        }
+        return out;
+    }
+    for (const line of trimmed.split("\n")) {
+        const cols = line.split("\t");
+        if (!cols[0])
+            continue;
+        out.set(cols[0].trim(), cols[1]?.trim() || null);
+    }
+    return out;
+}
+async function listServices(via, signal, http) {
+    if (via.id) {
+        const list = await spriteServiceList({ id: via.id, endpoint: via.endpoint, token: via.token }, signal, http ?? defaultSpritesHttp(via.token));
+        return new Map(list.map((s) => [s.name, s.state?.status ?? null]));
+    }
+    const bin = findSpriteEnv(via.spriteEnv);
+    if (!bin)
+        throw new Error("no sprite-env on PATH or in /.sprite/bin, and no sprite id to reach the Sprites API with");
+    const { stdout } = await execFileAsync(bin, ["services", "list"], { signal, timeout: 60000, maxBuffer: 16 * 1024 * 1024 });
+    return parseServicesList(stdout);
+}
+/** One GET of a health URL: true on 200. */
+export async function probeHealth(url, signal) {
+    try {
+        const timeout = AbortSignal.timeout(3000);
+        const res = await fetch(url, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout, redirect: "manual" });
+        await res.arrayBuffer().catch(() => undefined);
+        return res.status === 200;
+    }
+    catch {
+        return false;
+    }
+}
+const DOWN = new Set(["stopped", "failed", "stopping"]);
+/**
+ * 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 async function spriteServicesObserve(args, signal, http) {
+    const declared = await resolveDeclaredServices(args);
+    const probes = Math.max(1, args.probes ?? 3);
+    const interval = args.probeIntervalMs ?? 1000;
+    let states;
+    try {
+        states = await listServices(args, signal, http);
+    }
+    catch (err) {
+        const why = err instanceof Error ? err.message.split("\n")[0] : String(err);
+        return {
+            resources: declared.filter((s) => !s.optional).map((s) => ({ name: s.name, status: "unknown", detail: `the supervisor could not be read: ${why}` })),
+            skipped: declared.filter((s) => s.optional).map((s) => s.name),
+        };
+    }
+    const resources = [];
+    const skipped = [];
+    for (const service of declared) {
+        if (!states.has(service.name)) {
+            if (service.optional)
+                skipped.push(service.name);
+            else
+                resources.push({ name: service.name, status: "drifted", detail: "declared, but the supervisor has no such service" });
+            continue;
+        }
+        const state = states.get(service.name) ?? null;
+        if (state !== null && DOWN.has(state)) {
+            resources.push({ name: service.name, status: "drifted", detail: state });
+            continue;
+        }
+        if (service.health) {
+            let ok = false;
+            for (let i = 0; i < probes && !ok; i++) {
+                if (i > 0)
+                    await sleep(interval);
+                ok = await probeHealth(service.health, signal);
+            }
+            resources.push(ok
+                ? { name: service.name, status: "in-sync", detail: `${state ?? "listed"}, ${service.health} answers 200` }
+                : { name: service.name, status: "drifted", detail: `${state ?? "listed"}, ${service.health} does not answer 200 after ${probes} tries` });
+            continue;
+        }
+        resources.push(state === "running"
+            ? { name: service.name, status: "in-sync", detail: "running" }
+            : { name: service.name, status: "unknown", detail: `${state ?? "no state"}, and no health URL to probe` });
+    }
+    return { resources, skipped };
+}
+/**
+ * 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 async function spriteServiceRestart(args, signal, http) {
+    const name = args.name ?? process.env[CONVERGE_RESOURCE_ENV];
+    if (!name) {
+        throw new Error(`spriteServiceRestart: no service named: pass \`name\`, or run the Op from a ConvergeOp rule, which sets ${CONVERGE_RESOURCE_ENV}`);
+    }
+    const health = args.health ?? (args.services || args.servicesFile || args.box ? (await resolveDeclaredServices(args)).find((s) => s.name === name)?.health : undefined);
+    if (args.id) {
+        const client = http ?? defaultSpritesHttp(args.token);
+        await spriteServiceStop({ id: args.id, name, endpoint: args.endpoint, token: args.token }, signal, client);
+        await spriteServiceStart({ id: args.id, name, endpoint: args.endpoint, token: args.token }, signal, client);
+    }
+    else {
+        const bin = findSpriteEnv(args.spriteEnv);
+        if (!bin)
+            throw new Error("no sprite-env on PATH or in /.sprite/bin, and no sprite id to reach the Sprites API with");
+        await execFileAsync(bin, ["services", "restart", name], { signal, timeout: 120000 });
+    }
+    logProgress(`restarted: ${name}`);
+    if (!health)
+        return { name, healthy: null };
+    const until = Date.now() + (args.waitMs ?? 60000);
+    do {
+        if (await probeHealth(health, signal))
+            return { name, healthy: true };
+        await sleep(500);
+    } while (Date.now() < until && !signal?.aborted);
+    throw new Error(`${name} was restarted and does not answer ${health}`);
+}

package/dist/op/activities/sprite-services.js

@@ -0,0 +1,174 @@
+/**
+ * Sprite Services activities (#2711) — imperative create/get/list/start/stop/
+ * delete/logs over a Sprite's background services, the surface a box's door
+ * and hud run as long-lived services through (`sprite-env services`
+ * inside the sprite, `/v1/sprites/{id}/services/...` outside). Shared by the
+ * Sprites API, wisp (arugula-salad/wisp) and spritzer 0.6.0's container mode
+ * (INTENTIUS/spritzer#22).
+ *
+ * This is the imperative twin of `sprite-config.ts`'s `spriteApplyServices` —
+ * that one reconciles a whole desired service *set* (additive create-or-update,
+ * optionally started, no delete). These activities are the single-service
+ * primitives underneath it: create-and-start one service and watch it come
+ * up, inspect or list what's running, stop/start one by name, delete it, and
+ * read its log tail. An Op that provisions a box one service at a time (or
+ * needs delete, which `spriteApplyServices` doesn't expose) uses these
+ * directly; `spriteApplyServices` stays the batch-reconcile convenience on
+ * top of the same wire shapes.
+ *
+ * `spriteServiceCreate` is a `PUT` that both defines the service and starts
+ * it, streaming NDJSON progress (`started`, `stdout`, `stderr`, `exit`,
+ * `complete`) for a bounded `?duration` window (default 500ms — enough to
+ * surface an immediate failure, e.g. a missing binary, without holding the
+ * step open for spritzer's own 5s default). The stream is read to completion
+ * either way; the definitive result comes from a follow-up `GET` of the
+ * service (`spriteServiceGet`'s own logic), which throws if its `state.status`
+ * is `"failed"`. `spriteServiceStart` follows the same create-then-GET shape
+ * (`PUT` already started it; `start` is for a stopped service).
+ */
+import { resolveSpritesEndpoint, defaultSpritesHttp } from "./sprites.js";
+import { logProgress } from "./progress.js";
+// ── URL building (pure) ─────────────────────────────────────────────────────
+const servicesUrl = (base, id) => `${base}/v1/sprites/${encodeURIComponent(id)}/services`;
+const serviceUrl = (base, id, name) => `${servicesUrl(base, id)}/${encodeURIComponent(name)}`;
+const serviceLogsUrl = (base, id, name) => `${serviceUrl(base, id, name)}/logs`;
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Build the `PUT` create-or-update body. Pure. */
+export function spriteServiceCreateBody(args) {
+    return {
+        cmd: args.cmd,
+        ...(args.args !== undefined ? { args: args.args } : {}),
+        ...(args.env !== undefined ? { env: args.env } : {}),
+        ...(args.dir !== undefined ? { dir: args.dir } : {}),
+        ...(args.needs !== undefined ? { needs: args.needs } : {}),
+        ...(args.http_port !== undefined ? { http_port: args.http_port } : {}),
+    };
+}
+/**
+ * Parse a service log NDJSON body (`{type, data, timestamp, ...}` per line,
+ * terminated by a `complete` event) into a plain line tail — the `data` text
+ * of every non-`complete` event, in stream order. Pure.
+ */
+export function parseServiceLogNdjson(text) {
+    const lines = [];
+    for (const raw of text.split("\n")) {
+        const t = raw.trim();
+        if (!t)
+            continue;
+        const obj = safeJson(t);
+        if (!obj || obj.type === "complete")
+            continue;
+        if (typeof obj.data === "string")
+            lines.push(obj.data);
+    }
+    return lines;
+}
+// ── Activities ───────────────────────────────────────────────────────────────
+/**
+ * Create (or replace) and start a service. `PUT /v1/sprites/{id}/services/{name}`,
+ * streamed as NDJSON for `?duration` (mapped from `durationMs`). The stream is
+ * read to completion, then a `GET` fetches the definitive state; a `"failed"`
+ * status throws with the agent's own error text.
+ */
+export async function spriteServiceCreate(args, signal, http = defaultSpritesHttp(args.token)) {
+    const base = resolveSpritesEndpoint(args);
+    const durationMs = args.durationMs ?? 500;
+    const url = `${serviceUrl(base, args.id, args.name)}?duration=${durationMs}ms`;
+    const res = await http("PUT", url, spriteServiceCreateBody(args), undefined, signal);
+    if (res.status >= 300) {
+        throw new Error(`sprite ${args.id} service ${args.name} create failed (${res.status}): ${res.text}`);
+    }
+    const svc = await spriteServiceGet({ id: args.id, name: args.name, endpoint: args.endpoint, token: args.token }, signal, http);
+    if (svc.state.status === "failed") {
+        throw new Error(`sprite ${args.id} service ${args.name} failed to start: ${svc.state.error ?? "unknown error"}`);
+    }
+    logProgress(`service: sprite/${args.id}/${args.name} ${svc.state.status} (${base})`);
+    return svc;
+}
+/** Get one service. `GET /v1/sprites/{id}/services/{name}`. */
+export async function spriteServiceGet(args, signal, http = defaultSpritesHttp(args.token)) {
+    const base = resolveSpritesEndpoint(args);
+    const res = await http("GET", serviceUrl(base, args.id, args.name), undefined, undefined, signal);
+    if (res.status >= 300) {
+        throw new Error(`sprite ${args.id} service ${args.name} get failed (${res.status}): ${res.text}`);
+    }
+    return safeJson(res.text) ?? { name: args.name, cmd: "", state: { name: args.name, status: "stopped" } };
+}
+/** List every service on the sprite. `GET /v1/sprites/{id}/services`. */
+export async function spriteServiceList(args, signal, http = defaultSpritesHttp(args.token)) {
+    const base = resolveSpritesEndpoint(args);
+    const res = await http("GET", servicesUrl(base, args.id), undefined, undefined, signal);
+    if (res.status >= 300)
+        throw new Error(`sprite ${args.id} service list failed (${res.status}): ${res.text}`);
+    const parsed = safeJson(res.text);
+    return Array.isArray(parsed) ? parsed : [];
+}
+/**
+ * Start a stopped service. `POST /v1/sprites/{id}/services/{name}/start`,
+ * streamed as NDJSON for `?duration`, then a `GET` for the definitive state
+ * (same shape as `spriteServiceCreate`).
+ */
+export async function spriteServiceStart(args, signal, http = defaultSpritesHttp(args.token)) {
+    const base = resolveSpritesEndpoint(args);
+    const durationMs = args.durationMs ?? 500;
+    const url = `${serviceUrl(base, args.id, args.name)}/start?duration=${durationMs}ms`;
+    const res = await http("POST", url, undefined, undefined, signal);
+    if (res.status >= 300) {
+        throw new Error(`sprite ${args.id} service ${args.name} start failed (${res.status}): ${res.text}`);
+    }
+    const svc = await spriteServiceGet({ id: args.id, name: args.name, endpoint: args.endpoint, token: args.token }, signal, http);
+    if (svc.state.status === "failed") {
+        throw new Error(`sprite ${args.id} service ${args.name} failed to start: ${svc.state.error ?? "unknown error"}`);
+    }
+    logProgress(`service: sprite/${args.id}/${args.name} ${svc.state.status} (${base})`);
+    return svc;
+}
+/**
+ * Stop a running service (SIGTERM, then SIGKILL after the grace period).
+ * `POST /v1/sprites/{id}/services/{name}/stop`.
+ */
+export async function spriteServiceStop(args, signal, http = defaultSpritesHttp(args.token)) {
+    const base = resolveSpritesEndpoint(args);
+    const qs = args.timeoutMs !== undefined ? `?timeout=${args.timeoutMs}ms` : "";
+    const url = `${serviceUrl(base, args.id, args.name)}/stop${qs}`;
+    const res = await http("POST", url, undefined, undefined, signal);
+    if (res.status >= 300) {
+        throw new Error(`sprite ${args.id} service ${args.name} stop failed (${res.status}): ${res.text}`);
+    }
+    const svc = await spriteServiceGet({ id: args.id, name: args.name, endpoint: args.endpoint, token: args.token }, signal, http);
+    logProgress(`service: sprite/${args.id}/${args.name} ${svc.state.status} (${base})`);
+    return svc;
+}
+/**
+ * Delete a service, stopping it first (idempotent; a 404 means it is already
+ * gone). `DELETE /v1/sprites/{id}/services/{name}`.
+ */
+export async function spriteServiceDelete(args, signal, http = defaultSpritesHttp(args.token)) {
+    const base = resolveSpritesEndpoint(args);
+    const res = await http("DELETE", serviceUrl(base, args.id, args.name), undefined, undefined, signal);
+    if (res.status >= 300 && res.status !== 404) {
+        throw new Error(`sprite ${args.id} service ${args.name} delete failed (${res.status}): ${res.text}`);
+    }
+    logProgress(`deleted: sprite/${args.id}/${args.name}`);
+    return {};
+}
+/**
+ * Read a service's log tail. `GET /v1/sprites/{id}/services/{name}/logs`,
+ * parsed from NDJSON to a plain line array (`parseServiceLogNdjson`).
+ */
+export async function spriteServiceLogs(args, signal, http = defaultSpritesHttp(args.token)) {
+    const base = resolveSpritesEndpoint(args);
+    const qs = args.lines !== undefined ? `?lines=${args.lines}` : "";
+    const res = await http("GET", `${serviceLogsUrl(base, args.id, args.name)}${qs}`, undefined, undefined, signal);
+    if (res.status >= 300) {
+        throw new Error(`sprite ${args.id} service ${args.name} logs failed (${res.status}): ${res.text}`);
+    }
+    return { lines: parseServiceLogNdjson(res.text) };
+}

package/dist/op/activities/sprite-tasks.js

@@ -0,0 +1,57 @@
+/**
+ * Sprite keep-alive Tasks activities (#847) — a hold that prevents a Sprite from
+ * pausing while a session runs. While at least one task exists the Sprite stays
+ * active; the hold is refreshed on an interval and released on exit.
+ *
+ * Per the Sprites docs a task carries an `expire` (seconds or a duration string
+ * like `"5m"`/`"1h"`) with a **1-hour max per task**, so a session longer than
+ * that must refresh. The recommended shape is a short expiry refreshed on a
+ * shorter interval — 5-minute expiry / 60-second refresh — released on exit.
+ *
+ * These are the three primitives, not a magic looping hold: a phased Op creates
+ * the task around a session (`spriteTaskCreate`) and releases it after (in the
+ * happy path and in `onFailure`). A worker whose session can outlast the 1-hour
+ * cap wraps its own run in a `spriteTaskRefresh` loop (that ambient loop lives in
+ * the long-running caller, not a single serializable activity — a phased Op has
+ * no single step to hang it on). `spriteTaskRelease` is idempotent so a crash
+ * still frees the Sprite (and the task auto-expires if the release never lands).
+ *
+ * The task REST path is provisional (S6, #766); it mirrors the other endpoints'
+ * `/v1/sprites/{id}/...` shape. URL building is a pure helper so the path can
+ * move without touching callers.
+ */
+import { resolveSpritesEndpoint, defaultSpritesHttp } from "./sprites.js";
+/** The task REST base for a sprite. Pure. */
+export function spriteTasksUrl(base, id) {
+    return `${base}/v1/sprites/${encodeURIComponent(id)}/tasks`;
+}
+export function spriteTaskUrl(base, id, name) {
+    return `${spriteTasksUrl(base, id)}/${encodeURIComponent(name)}`;
+}
+/** Create a keep-alive task. `POST /v1/sprites/{id}/tasks`. */
+export async function spriteTaskCreate(args, signal, http = defaultSpritesHttp(args.token)) {
+    const base = resolveSpritesEndpoint(args);
+    const body = { name: args.name, ...(args.expire !== undefined ? { expire: args.expire } : {}) };
+    const res = await http("POST", spriteTasksUrl(base, args.id), body, undefined, signal);
+    if (res.status >= 300)
+        throw new Error(`sprite ${args.id} task create failed (${res.status}): ${res.text}`);
+    return { name: args.name };
+}
+/** Refresh a task's expiry. `PUT /v1/sprites/{id}/tasks/{name}`. */
+export async function spriteTaskRefresh(args, signal, http = defaultSpritesHttp(args.token)) {
+    const base = resolveSpritesEndpoint(args);
+    const body = args.expire !== undefined ? { expire: args.expire } : undefined;
+    const res = await http("PUT", spriteTaskUrl(base, args.id, args.name), body, undefined, signal);
+    if (res.status >= 300)
+        throw new Error(`sprite ${args.id} task refresh failed (${res.status}): ${res.text}`);
+    return { name: args.name };
+}
+/** Release a task (idempotent; a 404 means already gone). `DELETE /v1/sprites/{id}/tasks/{name}`. */
+export async function spriteTaskRelease(args, signal, http = defaultSpritesHttp(args.token)) {
+    const base = resolveSpritesEndpoint(args);
+    const res = await http("DELETE", spriteTaskUrl(base, args.id, args.name), undefined, undefined, signal);
+    if (res.status >= 300 && res.status !== 404) {
+        throw new Error(`sprite ${args.id} task release failed (${res.status}): ${res.text}`);
+    }
+    return {};
+}

package/dist/op/activities/sprites-contract.js

@@ -0,0 +1,87 @@
+/**
+ * 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 (lifecycle, filesystem, config, tasks)
+ * 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}`.
+ *
+ * #2711 adds the imperative Services activities (`./sprite-services.ts`).
+ * Several of them share a physical endpoint with `spriteApplyServices`'s own
+ * calls (one `PUT`/one `GET .../services`/one `.../start` — the reconcile
+ * activity and the single-service primitives are two callers of the same
+ * REST surface), so one row lists every activity that calls it, comma
+ * separated, rather than one row per activity — `contractKeys()` stays one
+ * key per physical endpoint. `spriteServiceDelete` and `spriteServiceLogs`
+ * are deliberately absent: spritzer's interpreter mode (the coverage test's
+ * oracle) doesn't implement them, only its container-mode agent does, which
+ * has no per-verb entry in `/_spritzer/health` (real.go reports the whole
+ * `/v1/sprites/{id}/services/...` proxy as one wildcard line — nothing to
+ * normalize-compare against a specific verb). They're exercised instead by
+ * `sprite-services.docker.integration.e2e.test.ts` against real container-mode
+ * spritzer. `spriteUrl` is absent for the same reason, plus its target
+ * (`/s/{name}/...`) isn't under `/v1/sprites` at all.
+ */
+/**
+ * The Sprites endpoints the fly sprite activities depend on, across the lifecycle
+ * (./sprites.ts), filesystem (./sprite-fs.ts), config reconcile
+ * (./sprite-config.ts), and keep-alive tasks (./sprite-tasks.ts) modules. Keep in
+ * sync with the activity implementations — the unit test asserts every sprite
+ * activity is represented, and the coverage test asserts the pinned spritzer
+ * serves each one.
+ */
+export const SPRITES_CONTRACT = [
+    // Lifecycle (./sprites.ts)
+    { method: "POST", path: "/v1/sprites", activity: "spriteCreate" },
+    { method: "WS", path: "/v1/sprites/{id}/exec", activity: "spriteExec" },
+    { method: "POST", path: "/v1/sprites/{id}/checkpoint", activity: "spriteCheckpoint" },
+    { method: "GET", path: "/v1/sprites/{id}/checkpoints", activity: "listCheckpoints" },
+    { method: "POST", path: "/v1/sprites/{id}/checkpoints/{cp}/restore", activity: "spriteRestore" },
+    { method: "DELETE", path: "/v1/sprites/{id}", activity: "spriteDestroy, spriteDelete" },
+    // Filesystem (./sprite-fs.ts)
+    { method: "PUT", path: "/v1/sprites/{id}/fs/write", activity: "spriteWriteFile" },
+    { method: "GET", path: "/v1/sprites/{id}/fs/read", activity: "spriteReadFile" },
+    { method: "GET", path: "/v1/sprites/{id}/fs/list", activity: "spriteListDir" },
+    { method: "DELETE", path: "/v1/sprites/{id}/fs/delete", activity: "spriteRemove" },
+    // Network policy (./sprite-config.ts)
+    { method: "GET", path: "/v1/sprites/{id}/policy/network", activity: "spriteApplyNetworkPolicy" },
+    { method: "POST", path: "/v1/sprites/{id}/policy/network", activity: "spriteApplyNetworkPolicy" },
+    // Services (./sprite-config.ts, ./sprite-services.ts)
+    { method: "GET", path: "/v1/sprites/{id}/services", activity: "spriteApplyServices, spriteServiceList" },
+    { method: "GET", path: "/v1/sprites/{id}/services/{svc}", activity: "spriteServiceGet" },
+    { method: "PUT", path: "/v1/sprites/{id}/services/{svc}", activity: "spriteApplyServices, spriteServiceCreate" },
+    { method: "POST", path: "/v1/sprites/{id}/services/{svc}/start", activity: "spriteApplyServices, spriteServiceStart" },
+    { method: "POST", path: "/v1/sprites/{id}/services/{svc}/stop", activity: "spriteServiceStop" },
+    // Keep-alive tasks (./sprite-tasks.ts)
+    { method: "POST", path: "/v1/sprites/{id}/tasks", activity: "spriteTaskCreate" },
+    { method: "PUT", path: "/v1/sprites/{id}/tasks/{name}", activity: "spriteTaskRefresh" },
+    { method: "DELETE", path: "/v1/sprites/{id}/tasks/{name}", activity: "spriteTaskRelease" },
+];
+/**
+ * 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 function normalizeEndpoint(method, path) {
+    const m = method === "WS" ? "GET" : method.toUpperCase();
+    const p = path.replace(/\{[^}]+\}/g, "{}");
+    return `${m} ${p}`;
+}
+/** The contract as a set of normalized `METHOD path` keys. */
+export function contractKeys() {
+    return new Set(SPRITES_CONTRACT.map((e) => normalizeEndpoint(e.method, e.path)));
+}

package/dist/op/activities/sprites-emulator.js

@@ -0,0 +1,72 @@
+import { emulatorLifecycle } from "@intentius/chant/op";
+import { SPRITZER_IMAGE, SPRITZER_CONTAINER_IMAGE } from "./emulator-images.js";
+// spritzer is a stateful fake of the Fly Sprites API — a plain 200 on its health
+// endpoint means ready. The local target for the sprite activities; point them
+// there with SPRITES_BASE_URL. Shared lifecycle: emulatorLifecycle (the same
+// helper that boots mudflaps for fly).
+export const SPRITZER_SPEC = {
+    name: "chant-spritzer",
+    image: SPRITZER_IMAGE,
+    containerPort: 4290,
+    healthPath: "/_spritzer/health",
+    upstream: { repo: "intentius/spritzer" },
+};
+/** The Sprites half of fly's emulator capability (#1345). */
+export const SPRITZER_EMULATOR = {
+    spec: SPRITZER_SPEC,
+    env: (endpoint) => ({ SPRITES_BASE_URL: endpoint }),
+};
+const spritzer = emulatorLifecycle(SPRITZER_SPEC);
+export const spritesExistsCommand = spritzer.existsCommand;
+export const spritesRmCommand = spritzer.rmCommand;
+export const spritesHealthUrl = spritzer.healthUrl;
+/** The Sprites endpoint URL (what the sprite activities' `SPRITES_BASE_URL`/`endpoint` points at). */
+export const spritesEndpoint = spritzer.endpoint;
+export const spritesRunCommand = (args = {}) => spritzer.runCommand(args);
+/** Boot a local spritzer (Fly Sprites API emulator) in Docker and return its endpoint. */
+export const spritesUp = (args = {}, signal) => spritzer.up(args, signal);
+/** Stop and remove the local spritzer container (no-op if already gone). */
+export const spritesDown = (args = {}, signal) => spritzer.down(args, signal);
+// ── Container exec mode (#2711, INTENTIUS/spritzer#22) ─────────────────────────
+//
+// A second, distinct spritzer lifecycle: `SPRITZER_EXEC=container` with the
+// Docker runtime, so each sprite it makes is a real container — the mode the
+// Services CRUD activities (`./sprite-services.ts`) and `spriteUrl` need (real
+// processes, a real sprite URL), and that `SPRITZER_SPEC` above (interpreter
+// mode, the default everything else tests against) does not run. The Docker
+// socket is mounted read-write so spritzer can create/exec/delete sibling
+// sprite containers through it (docker-outside-of-docker); no port publishing
+// is needed for the sprites themselves — spritzer reaches them by exec, and
+// proxies their URL (`/s/{name}/...`) through the one published port.
+/** Container exec mode spritzer, pinned to {@link SPRITZER_CONTAINER_IMAGE} (0.6.0, the first release with this mode). */
+export const SPRITZER_CONTAINER_SPEC = {
+    name: "chant-spritzer-container",
+    image: SPRITZER_CONTAINER_IMAGE,
+    containerPort: 4290,
+    healthPath: "/_spritzer/health",
+    runArgs: [
+        // The image runs as `nonroot` by default, which cannot open a
+        // group/other-unwritable host socket — root inside the container is
+        // still an unprivileged Linux user account relative to the host/Docker
+        // Desktop VM, no different from any other `docker run` that mounts the
+        // socket.
+        "--user",
+        "root",
+        "-e",
+        "SPRITZER_EXEC=container",
+        "-e",
+        "SPRITZER_RUNTIME=docker",
+        "-v",
+        "/var/run/docker.sock:/var/run/docker.sock",
+    ],
+    upstream: { repo: "intentius/spritzer" },
+};
+const spritzerContainer = emulatorLifecycle(SPRITZER_CONTAINER_SPEC);
+export const spritesContainerRunCommand = (args = {}) => spritzerContainer.runCommand(args);
+export const spritesContainerExistsCommand = spritzerContainer.existsCommand;
+export const spritesContainerRmCommand = spritzerContainer.rmCommand;
+export const spritesContainerHealthUrl = spritzerContainer.healthUrl;
+/** Boot a local spritzer in container exec mode (Docker runtime) and return its endpoint. */
+export const spritesContainerUp = (args = {}, signal) => spritzerContainer.up(args, signal);
+/** Stop and remove the local container-exec-mode spritzer (no-op if already gone). Sprite containers it made are the caller's to clean up (see the integration test). */
+export const spritesContainerDown = (args = {}, signal) => spritzerContainer.down(args, signal);