spawnfile 0.1.17 → 0.1.19

package/dist/release/releaseTypes.d.ts

@@ -0,0 +1,94 @@
+import type { ResolvedAuthProfile } from "../auth/index.js";
+import type { CompileProjectResult } from "../compiler/compileProject.js";
+import type { DockerDeploymentTarget } from "../deployment/index.js";
+import type { Availability, DrainWait, RuntimeControlTarget, WaitForDrainedOptions } from "./drainControl.js";
+import type { NotifierConfig, NotifyResult, ReleaseNotification } from "./notify.js";
+import type { PostDeployContext, PostDeployHook, PostDeployResult } from "./postDeploy.js";
+import type { PruneResult, RunningUnit, SettleOptions } from "./releaseDocker.js";
+export declare const DAIMON_CONTROL_TOKEN_ENV = "SPAWNFILE_DAIMON_CONTROL_TOKEN";
+export interface ReleaseRequest {
+    authProfile?: ResolvedAuthProfile | null;
+    authProfileName?: string | null;
+    /** `release` (default) builds workspace bundles only from clean committed inputs. */
+    bundleIdentity: "dev" | "release";
+    deployment: string;
+    dockerCommand: string;
+    dockerContext?: string;
+    /** Set from the pinned target when it is a `DOCKER_HOST` daemon. */
+    dockerHost?: string;
+    /** False only when the operator explicitly accepts killing in-flight turns. */
+    drain: boolean;
+    drainPollMs: number;
+    drainTimeoutMs: number;
+    envFileEnv: Record<string, string>;
+    envFilePath?: string;
+    force: boolean;
+    imageRepository?: string;
+    inputPath: string;
+    log: (line: string) => void;
+    notifier: NotifierConfig;
+    notifyDeferredAfterMs: number;
+    now?: () => Date;
+    outputDirectory?: string;
+    /** Runs once the new container settled and admits; must exit 0 before the release is recorded. */
+    postDeploy?: PostDeployHook | null;
+    /** Overrides `<SPAWNFILE_HOME>/releases`. */
+    releaseRoot?: string;
+    settle: SettleOptions;
+    signal?: AbortSignal;
+    /** The Docker daemon every step of this release talks to, pinned once at the start. */
+    target?: DockerDeploymentTarget;
+}
+export interface CompiledRelease {
+    compileMs: number;
+    compileResult: CompileProjectResult;
+    identity: string;
+    repository: string;
+}
+export interface BuiltRelease {
+    buildMs: number | null;
+    imageId: string;
+    imageTag: string;
+    skipped: boolean;
+}
+export interface DeployedRelease {
+    containerName: string;
+    deployMs: number;
+}
+export interface PreparedInputs {
+    authProfile: ResolvedAuthProfile | null;
+    envFileEnv: Record<string, string>;
+}
+/**
+ * Every effect a release has, injectable so the ORDER (drain before deploy,
+ * resume on abort, never deploy on a drain timeout) is asserted by tests
+ * rather than by a comment.
+ */
+export interface ReleaseDependencies {
+    build(request: ReleaseRequest, compiled: CompiledRelease, imageTag: string): Promise<BuiltRelease>;
+    compile(request: ReleaseRequest): Promise<CompiledRelease>;
+    /** Deploys while the caller holds the deployment lock (see `lockDeployment`). */
+    deploy(request: ReleaseRequest, imageTag: string): Promise<DeployedRelease>;
+    inspectUnit(request: ReleaseRequest, containerRef: string): Promise<RunningUnit | null>;
+    /** The same home lock `up` takes, held from the drain through the swap. */
+    lockDeployment(deployment: string): Promise<() => Promise<void>>;
+    notify(config: NotifierConfig, notification: ReleaseNotification): Promise<NotifyResult>;
+    /** Reads the env file and auth profile inside the release, so their failures are reported like any other. */
+    prepare(request: ReleaseRequest): Promise<PreparedInputs>;
+    prune(request: ReleaseRequest, repository: string, keep: readonly (string | null)[]): Promise<PruneResult>;
+    /** Runtime kinds inside the running image, from its embedded distribution report. */
+    runtimesOf(request: ReleaseRequest, imageId: string): Promise<string[]>;
+    requestDrain(target: RuntimeControlTarget): Promise<Availability>;
+    /**
+     * The Docker daemon this release talks to, with its endpoint fingerprint:
+     * an explicit `--context`, else what the Docker CLI would use
+     * (`DOCKER_HOST`, `DOCKER_CONTEXT` or the selected context).
+     */
+    pinTarget(request: ReleaseRequest): Promise<DockerDeploymentTarget>;
+    /** Throws when a recorded target's endpoint is no longer the one its name resolves to. */
+    verifyTarget(request: ReleaseRequest, target: DockerDeploymentTarget): Promise<void>;
+    requestResume(target: RuntimeControlTarget): Promise<Availability>;
+    runPostDeploy(request: ReleaseRequest, hook: PostDeployHook, context: PostDeployContext): Promise<PostDeployResult>;
+    settle(request: ReleaseRequest, containerRef: string): Promise<RunningUnit>;
+    waitForDrained(target: RuntimeControlTarget, options: WaitForDrainedOptions): Promise<DrainWait>;
+}

package/dist/release/releaseTypes.js

@@ -0,0 +1 @@
+export const DAIMON_CONTROL_TOKEN_ENV = "SPAWNFILE_DAIMON_CONTROL_TOKEN";

package/dist/release/runRelease.d.ts

@@ -0,0 +1,9 @@
+import { type ReleaseDependencies, type ReleaseRequest } from "./releaseTypes.js";
+import { type ReleaseOutcome } from "./types.js";
+/**
+ * compile → identity → (unchanged? stop) → build → drain → deploy → settle →
+ * resume → post-deploy → record → prune. The ledger is written last because it claims
+ * "this identity is RUNNING"; written earlier it would claim a container that
+ * never came up, and the next run would see nothing to do.
+ */
+export declare const runRelease: (request: ReleaseRequest, deps: ReleaseDependencies) => Promise<ReleaseOutcome>;

package/dist/release/runRelease.js

@@ -0,0 +1,218 @@
+import { rm } from "node:fs/promises";
+import { normalizeDeploymentName } from "../deployment/index.js";
+import { controlTargetFor, recoverInterruptedDrain, requestForTarget, resolveControlToken } from "./drainPhase.js";
+import { acquireReleaseLock, appendReleaseLog, postDeployPending, ensureReleaseDirectory, readReleaseLedger, resolveReleasePaths, writeJsonAtomic, writeReleaseLedger } from "./ledger.js";
+import { createNotification } from "./notify.js";
+import { clearDeferral, markDeferralNotified, recordDeferral } from "./pending.js";
+import { releaseImageTag } from "./releaseDocker.js";
+import { DAIMON_CONTROL_TOKEN_ENV } from "./releaseTypes.js";
+import { drainAndSwap, releaseContainerName } from "./swap.js";
+import { ReleaseError, isReleaseError } from "./types.js";
+/**
+ * compile → identity → (unchanged? stop) → build → drain → deploy → settle →
+ * resume → post-deploy → record → prune. The ledger is written last because it claims
+ * "this identity is RUNNING"; written earlier it would claim a container that
+ * never came up, and the next run would see nothing to do.
+ */
+export const runRelease = async (request, deps) => {
+    // One spelling everywhere: storage, the container name, the lock and `up` all normalize it.
+    request.deployment = normalizeDeploymentName(request.deployment);
+    const paths = resolveReleasePaths(request.deployment, request.releaseRoot);
+    const progress = { identity: null, stage: "lock" };
+    let unlock = null;
+    try {
+        await ensureReleaseDirectory(paths);
+        unlock = await acquireReleaseLock(paths);
+        progress.stage = "prepare";
+        Object.assign(request, await deps.prepare(request));
+        progress.stage = "recover";
+        await recoverInterruptedDrain(request, deps, paths);
+        progress.stage = "target";
+        const pinned = requestForTarget(request, await deps.pinTarget(request));
+        return await releaseLocked(pinned, deps, paths, progress);
+    }
+    catch (error) {
+        return fail(request, deps, paths, progress, error);
+    }
+    finally {
+        await unlock?.().catch(() => undefined);
+    }
+};
+const releaseLocked = async (request, deps, paths, progress) => {
+    const started = Date.now();
+    progress.stage = "compile";
+    const compiled = await deps.compile(request).catch((error) => {
+        throw new ReleaseError("build-failed", `compile failed: ${error.message}`, { cause: error });
+    });
+    progress.identity = compiled.identity;
+    const imageTag = releaseImageTag(compiled.repository, compiled.identity);
+    progress.stage = "inspect";
+    const ledger = await readReleaseLedger(paths.ledger);
+    const running = await deps.inspectUnit(request, releaseContainerName(request.deployment));
+    // A post-deploy command that failed (or never finished) leaves its marker: the
+    // running container may be the recorded image, but the release is not done.
+    const hookPending = await postDeployPending(paths.postDeploy);
+    if (!hookPending && isUnchanged(request, ledger, compiled.identity, running)) {
+        await clearDeferral(paths.pending);
+        request.log(`release: ${compiled.identity.slice(0, 19)} is already running as ${ledger.image_tag}; nothing to do`);
+        return { identity: compiled.identity, imageTag: ledger.image_tag, kind: "unchanged" };
+    }
+    if (request.drain && running?.running && resolveControlToken(request) === null) {
+        throw new ReleaseError("blocked", `${DAIMON_CONTROL_TOKEN_ENV} is not set in the env file or environment; a drained release needs the running deployment's control token`);
+    }
+    request.log(ledger
+        ? `release: ${compiled.identity.slice(0, 19)} differs from the released ${ledger.identity.slice(0, 19)} (${ledger.image_tag}); releasing`
+        : `release: nothing recorded as released for ${request.deployment}; releasing ${compiled.identity.slice(0, 19)}`);
+    // The tag about to be built is kept too: a retry after a failed deploy reuses it instead of rebuilding.
+    await pruneQuietly(request, deps, compiled.repository, [imageTag, ledger?.image_tag ?? null, ledger?.previous_image_tag ?? null]);
+    progress.stage = "build";
+    const built = await deps.build(request, compiled, imageTag).catch((error) => {
+        throw new ReleaseError("build-failed", `image build failed: ${error.message}`, { cause: error });
+    });
+    request.log(built.skipped ? `release: ${imageTag} already built; build skipped` : `release: built ${imageTag} in ${Math.round((built.buildMs ?? 0) / 1000)}s`);
+    progress.stage = "deploy";
+    if (request.signal?.aborted)
+        throw new ReleaseError("interrupted", "the release was interrupted before draining; nothing was paused or deployed");
+    // The same home lock `up` takes, held from before the drain until the ledger
+    // names what is running: no concurrent `up` can replace the drained
+    // container, or the candidate before it is recorded.
+    const unlockDeployment = await deps.lockDeployment(request.deployment).catch((error) => {
+        throw new ReleaseError("blocked", `cannot lock the deployment: ${error.message}`);
+    });
+    try {
+        return await swapAndRecord(request, deps, paths, progress, { built, compiled, imageTag, ledger, started });
+    }
+    finally {
+        await unlockDeployment().catch(() => undefined);
+    }
+};
+const swapAndRecord = async (request, deps, paths, progress, { built, compiled, imageTag, ledger, started }) => {
+    const swap = await drainAndSwap(request, deps, paths, imageTag);
+    if (swap.kind === "deferred")
+        return defer(request, deps, paths, compiled.identity);
+    const { deployed, drained } = swap;
+    progress.stage = "settle";
+    const settled = await deps.settle(request, deployed.containerName);
+    if (settled.imageId !== built.imageId) {
+        throw new ReleaseError("deploy-failed", `the settled container runs ${settled.imageId}, not the built ${built.imageId}`);
+    }
+    if (request.drain) {
+        progress.stage = "resume";
+        try {
+            await deps.requestResume(controlTargetFor(request, settled.id, settled.imageId));
+        }
+        catch (error) {
+            throw new ReleaseError("resume-failed", `the new container did not confirm admission: ${error.message}`);
+        }
+    }
+    if (request.postDeploy) {
+        progress.stage = "post-deploy";
+        await writeJsonAtomic(paths.postDeploy, { at: (request.now?.() ?? new Date()).toISOString(), identity: compiled.identity }).catch((error) => {
+            throw new ReleaseError("post-deploy-failed", `cannot record that a post-deploy command is pending, so it was not run: ${error.message}`);
+        });
+        await runPostDeployStep(request, deps, request.postDeploy, {
+            containerName: deployed.containerName, deployment: request.deployment, identity: compiled.identity, imageId: settled.imageId, imageTag
+        });
+    }
+    progress.stage = "record";
+    const timings = {
+        build_ms: built.buildMs,
+        compile_ms: compiled.compileMs,
+        deploy_ms: deployed.deployMs,
+        drain_ms: drained.drainMs,
+        total_ms: Date.now() - started
+    };
+    const next = {
+        compile_fingerprint: compiled.compileResult.report.compile_fingerprint ?? "unknown",
+        deployment: request.deployment,
+        identity: compiled.identity,
+        image_id: settled.imageId,
+        image_tag: imageTag,
+        previous_image_tag: ledger && ledger.image_tag !== imageTag ? ledger.image_tag : ledger?.previous_image_tag ?? null,
+        released_at: (request.now?.() ?? new Date()).toISOString(),
+        timings,
+        version: "spawnfile.release-ledger.v1"
+    };
+    await writeReleaseLedger(paths.ledger, next).catch((error) => {
+        throw new ReleaseError("ledger-failed", `the deployment is running but the release ledger could not be written (every later run will redeploy until it can): ${error.message}`);
+    });
+    await rm(paths.postDeploy, { force: true }).catch((error) => {
+        request.log(`release: cannot clear the post-deploy marker, so the next run releases again: ${error.message}`);
+    });
+    await appendReleaseLog(paths.log, { at: next.released_at, deployment: request.deployment, identity: compiled.identity, image_tag: imageTag, outcome: "released", timings }).catch(() => undefined);
+    await clearDeferral(paths.pending).catch(() => undefined);
+    await pruneQuietly(request, deps, compiled.repository, [imageTag, next.previous_image_tag]);
+    request.log(`release: ${imageTag} deployed, settled and recorded (build ${timings.build_ms === null ? "skipped" : `${Math.round(timings.build_ms / 1000)}s`}, drain ${Math.round((timings.drain_ms ?? 0) / 1000)}s, total ${Math.round(timings.total_ms / 1000)}s)`);
+    return { identity: compiled.identity, imageId: settled.imageId, imageTag, kind: "released", timings };
+};
+/** A failed hook leaves the release unrecorded: the next run deploys again and reruns it. */
+const runPostDeployStep = async (request, deps, hook, context) => {
+    if (request.signal?.aborted)
+        throw new ReleaseError("interrupted", "the release was interrupted after deploying; the post-deploy command did not run and nothing was recorded");
+    let result;
+    try {
+        result = await deps.runPostDeploy(request, hook, context);
+    }
+    catch (error) {
+        throw new ReleaseError("post-deploy-failed", `the post-deploy command could not run: ${error.message}`);
+    }
+    const output = result.output.trim();
+    if (output)
+        request.log(`release: post-deploy output:\n${output}`);
+    if (request.signal?.aborted)
+        throw new ReleaseError("interrupted", "the release was interrupted while the post-deploy command ran; nothing was recorded");
+    if (result.timedOut)
+        throw new ReleaseError("post-deploy-failed", `the post-deploy command did not finish within ${Math.round(hook.timeoutMs / 1000)}s`);
+    if (result.exitCode !== 0)
+        throw new ReleaseError("post-deploy-failed", `the post-deploy command exited ${result.exitCode ?? "by signal"}${output ? `: ${output.slice(-300)}` : ""}`);
+    request.log("release: post-deploy command succeeded");
+};
+/** Unchanged means the recorded identity is the one the container is actually running, not merely the one last built. */
+const isUnchanged = (request, ledger, identity, running) => !request.force && ledger !== null && ledger.identity === identity && running !== null && running.running && running.imageId === ledger.image_id;
+const pruneQuietly = async (request, deps, repository, keep) => {
+    try {
+        const pruned = await deps.prune(request, repository, keep);
+        for (const tag of pruned.removed)
+            request.log(`release: removed old image ${tag}`);
+    }
+    catch (error) {
+        request.log(`release: image prune skipped (${error.message.slice(0, 160)})`);
+    }
+};
+const defer = async (request, deps, paths, identity) => {
+    const decision = await recordDeferral(paths.pending, identity, { notifyAfterMs: request.notifyDeferredAfterMs, ...(request.now ? { now: request.now() } : {}) });
+    const hours = Math.floor(decision.ageMs / 3_600_000);
+    const message = decision.trackingBroken
+        ? `release deferred (running turns did not finish within the drain bound) and ${decision.trackingBroken}`
+        : `release deferred: running turns did not finish within the drain bound; pending ${hours}h`;
+    request.log(`release: ${message}; admission resumed, nothing deployed, retry on the next run`);
+    const at = (request.now?.() ?? new Date()).toISOString();
+    await appendReleaseLog(paths.log, { at, deployment: request.deployment, identity, message, outcome: "deferred", reason: "release-deferred" }).catch(() => undefined);
+    const notified = decision.notify ? await notifyAndLog(request, deps, paths, "release-deferred", message, identity) : false;
+    if (notified && !decision.trackingBroken)
+        await markDeferralNotified(paths.pending, decision.pending).catch(() => undefined);
+    return { identity, kind: "deferred", message, notified };
+};
+const fail = async (request, deps, paths, progress, error) => {
+    const reason = isReleaseError(error) ? error.reason : "blocked";
+    const message = `${reason} at ${progress.stage}: ${error instanceof Error ? error.message : String(error)}`;
+    request.log(`release FAILED: ${message}`);
+    const at = (request.now?.() ?? new Date()).toISOString();
+    await appendReleaseLog(paths.log, { at, deployment: request.deployment, identity: progress.identity, message, outcome: "failed", reason }).catch(() => undefined);
+    const notified = await notifyAndLog(request, deps, paths, reason, message, progress.identity);
+    return { identity: progress.identity, kind: "failed", message, notified, reason };
+};
+const notifyAndLog = async (request, deps, paths, reason, message, identity) => {
+    if (request.notifier.kind === "none")
+        return false;
+    const notification = createNotification({ deployment: request.deployment, identity, message, reason, ...(request.now ? { now: request.now() } : {}) });
+    const result = await deps.notify(request.notifier, notification).catch((error) => ({ channel: request.notifier.kind, delivered: false, error: error.message }));
+    if (!result.delivered)
+        request.log(`release: notifier did not deliver (${result.error ?? "unknown"}); the message is in ${paths.log}`);
+    await appendReleaseLog(paths.log, {
+        at: notification.at, deployment: request.deployment, identity, message: notification.message,
+        notified: { channel: result.channel, delivered: result.delivered, ...(result.error ? { error: result.error } : {}) },
+        outcome: "notified", reason
+    }).catch(() => undefined);
+    return result.delivered;
+};

package/dist/release/swap.d.ts

@@ -0,0 +1,23 @@
+import { type DrainOutcome } from "./drainPhase.js";
+import type { ReleasePaths } from "./ledger.js";
+import type { DeployedRelease, ReleaseDependencies, ReleaseRequest } from "./releaseTypes.js";
+/** Runtimes whose admission a release can pause through a published control contract. */
+export declare const DRAINABLE_RUNTIMES: ReadonlySet<string>;
+/** `up --image` names the deployment's container this way; a release replaces exactly that container. */
+export declare const releaseContainerName: (deployment: string) => string;
+export type SwapOutcome = {
+    deployed: DeployedRelease;
+    drained: DrainOutcome;
+    kind: "deployed";
+} | {
+    drained: DrainOutcome;
+    kind: "deferred";
+};
+/**
+ * Drain and swap. The caller holds the deployment's home lock, so no
+ * concurrent `up` can replace the drained container between the drain and
+ * the deploy. The container is inspected again under the lock (a long build may have outlived
+ * the first inspection) and once more after the drain: a different container,
+ * or one that restarted and therefore admits again, aborts the release.
+ */
+export declare const drainAndSwap: (request: ReleaseRequest, deps: ReleaseDependencies, paths: ReleasePaths, imageTag: string) => Promise<SwapOutcome>;

package/dist/release/swap.js

@@ -0,0 +1,55 @@
+import { clearDrainMarker, drainForRelease, resumeAfterFailedDeploy, resumeDrained } from "./drainPhase.js";
+import { ReleaseError } from "./types.js";
+/** Runtimes whose admission a release can pause through a published control contract. */
+export const DRAINABLE_RUNTIMES = new Set(["daimon"]);
+/** `up --image` names the deployment's container this way; a release replaces exactly that container. */
+export const releaseContainerName = (deployment) => `spawnfile-${deployment}`;
+/**
+ * Drain and swap. The caller holds the deployment's home lock, so no
+ * concurrent `up` can replace the drained container between the drain and
+ * the deploy. The container is inspected again under the lock (a long build may have outlived
+ * the first inspection) and once more after the drain: a different container,
+ * or one that restarted and therefore admits again, aborts the release.
+ */
+export const drainAndSwap = async (request, deps, paths, imageTag) => {
+    const containerName = releaseContainerName(request.deployment);
+    const target = await deps.inspectUnit(request, containerName);
+    if (request.drain && target?.running) {
+        const runtimes = await deps.runtimesOf(request, target.imageId).catch((error) => {
+            throw new ReleaseError("blocked", `cannot read which runtimes the running image holds, so it cannot be shown drainable: ${error.message}`);
+        });
+        const undrainable = [...new Set(runtimes)].filter((runtime) => !DRAINABLE_RUNTIMES.has(runtime));
+        if (runtimes.length === 0 || undrainable.length > 0) {
+            throw new ReleaseError("blocked", `the running container holds runtimes without a drain contract (${undrainable.join(", ") || "none listed"}); draining it could not stop their turns. Use --no-drain to deploy over them deliberately`);
+        }
+    }
+    const drained = await drainForRelease(request, deps, paths, target);
+    if (drained.kind === "timeout")
+        return { drained, kind: "deferred" };
+    if (drained.kind === "drained" && target) {
+        // Anything that stops the release between the drain and the deploy resumes the drained container.
+        try {
+            const now = await deps.inspectUnit(request, containerName);
+            if (now === null || now.id !== target.id || now.restartCount !== target.restartCount || !now.running) {
+                throw new ReleaseError("drain-failed", "the drained container was replaced or restarted before the deploy; a restarted runtime admits again, so nothing was deployed");
+            }
+            if (request.signal?.aborted)
+                throw new ReleaseError("interrupted", "the release was interrupted after draining; admission resumed, nothing deployed");
+        }
+        catch (error) {
+            await resumeDrained(request, deps, paths, target);
+            throw error instanceof ReleaseError ? error : new ReleaseError("drain-failed", `cannot confirm the drained container before deploying: ${error.message}`);
+        }
+    }
+    let deployed;
+    try {
+        deployed = await deps.deploy(request, imageTag);
+    }
+    catch (error) {
+        await resumeAfterFailedDeploy(request, deps, paths, containerName);
+        throw new ReleaseError("deploy-failed", `deploy failed: ${error.message}`, { cause: error });
+    }
+    // The drained container was replaced; its drain ended with its process.
+    await clearDrainMarker(paths);
+    return { deployed, drained, kind: "deployed" };
+};

package/dist/release/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The fixed vocabulary a release failure is reported in. A notifier receives
+ * exactly one of these words, so whoever reads the notification learns a small
+ * closed set rather than free text; the detail travels separately.
+ */
+export declare const RELEASE_FAILURE_REASONS: readonly ["blocked", "build-failed", "drain-failed", "deploy-failed", "health-failed", "resume-failed", "post-deploy-failed", "ledger-failed", "interrupted", "release-deferred"];
+export type ReleaseFailureReason = (typeof RELEASE_FAILURE_REASONS)[number];
+/** Carries the reason word with the error so the orchestrator never guesses it. */
+export declare class ReleaseError extends Error {
+    readonly reason: ReleaseFailureReason;
+    constructor(reason: ReleaseFailureReason, message: string, options?: ErrorOptions);
+}
+export declare const isReleaseError: (value: unknown) => value is ReleaseError;
+export interface ReleaseTimings {
+    build_ms: number | null;
+    compile_ms: number;
+    deploy_ms: number | null;
+    drain_ms: number | null;
+    total_ms: number;
+}
+/**
+ * `released`: a new image is running and recorded. `unchanged`: the recorded
+ * identity is the one running, nothing was built or touched. `deferred`: the
+ * running organization did not drain within the bound, the release was
+ * abandoned before deploying and admission resumed. `failed`: see `reason`.
+ */
+export type ReleaseOutcome = {
+    identity: string;
+    imageTag: string;
+    kind: "unchanged";
+} | {
+    identity: string;
+    imageId: string;
+    imageTag: string;
+    kind: "released";
+    timings: ReleaseTimings;
+} | {
+    identity: string;
+    kind: "deferred";
+    message: string;
+    notified: boolean;
+} | {
+    identity: string | null;
+    kind: "failed";
+    message: string;
+    notified: boolean;
+    reason: ReleaseFailureReason;
+};
+/** Exit codes: 0 released/unchanged, 75 (EX_TEMPFAIL) deferred, 1 failed. */
+export declare const releaseExitCode: (outcome: ReleaseOutcome) => number;

package/dist/release/types.js

@@ -0,0 +1,29 @@
+/**
+ * The fixed vocabulary a release failure is reported in. A notifier receives
+ * exactly one of these words, so whoever reads the notification learns a small
+ * closed set rather than free text; the detail travels separately.
+ */
+export const RELEASE_FAILURE_REASONS = Object.freeze([
+    "blocked",
+    "build-failed",
+    "drain-failed",
+    "deploy-failed",
+    "health-failed",
+    "resume-failed",
+    "post-deploy-failed",
+    "ledger-failed",
+    "interrupted",
+    "release-deferred"
+]);
+/** Carries the reason word with the error so the orchestrator never guesses it. */
+export class ReleaseError extends Error {
+    reason;
+    constructor(reason, message, options) {
+        super(message, options);
+        this.reason = reason;
+        this.name = "ReleaseError";
+    }
+}
+export const isReleaseError = (value) => value instanceof ReleaseError;
+/** Exit codes: 0 released/unchanged, 75 (EX_TEMPFAIL) deferred, 1 failed. */
+export const releaseExitCode = (outcome) => outcome.kind === "failed" ? 1 : outcome.kind === "deferred" ? 75 : 0;

package/dist/report/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./createDiagnostic.js";
 export * from "./createReport.js";
 export * from "./types.js";
+export * from "./recording.js";
 export * from "./writeReport.js";

package/dist/report/index.js

@@ -1,4 +1,5 @@
 export * from "./createDiagnostic.js";
 export * from "./createReport.js";
 export * from "./types.js";
+export * from "./recording.js";
 export * from "./writeReport.js";

package/dist/report/recording.d.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+/** Portable compiled facts, persisted with the deployment so sync never recompiles. */
+export declare const recordingAgentSchema: z.ZodObject<{
+    node_id: z.ZodString;
+    slug: z.ZodString;
+    directory: z.ZodString;
+    keep_ms: z.ZodNumber;
+    networks: z.ZodArray<z.ZodString>;
+    memory: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        declared_by: z.ZodString;
+        ledger_path: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    feeds: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        volume_name: z.ZodString;
+    }, z.core.$strict>>;
+    resources: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            git: "git";
+            bundle: "bundle";
+        }>;
+    }, z.core.$strict>>;
+    snapshots: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type RecordingAgentReport = z.infer<typeof recordingAgentSchema>;
+/** Optional members preserve S1 records; sync requires the compiled agents member. */
+export declare const recordingReportSchema: z.ZodObject<{
+    keep_ms: z.ZodNumber;
+    memory_mount_ids: z.ZodArray<z.ZodString>;
+    recording_mount_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    agents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        node_id: z.ZodString;
+        slug: z.ZodString;
+        directory: z.ZodString;
+        keep_ms: z.ZodNumber;
+        networks: z.ZodArray<z.ZodString>;
+        memory: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            declared_by: z.ZodString;
+            ledger_path: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>;
+        feeds: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            volume_name: z.ZodString;
+        }, z.core.$strict>>;
+        resources: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                git: "git";
+                bundle: "bundle";
+            }>;
+        }, z.core.$strict>>;
+        snapshots: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;

package/dist/report/recording.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+const text = z.string().min(1);
+const mountId = text.regex(/^[A-Za-z0-9][A-Za-z0-9_.-]*$/u).refine((value) => !value.includes(".."));
+const containerPath = text.startsWith("/").refine((value) => !value.includes("\0"));
+const keepMs = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+/** Portable compiled facts, persisted with the deployment so sync never recompiles. */
+export const recordingAgentSchema = z.object({
+    node_id: text,
+    slug: text.regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u),
+    directory: containerPath,
+    keep_ms: keepMs,
+    networks: z.array(text),
+    memory: z.array(z.object({ id: text, declared_by: text, ledger_path: containerPath.nullable() }).strict()),
+    feeds: z.array(z.object({ id: text, volume_name: text }).strict()),
+    resources: z.array(z.object({ id: text, kind: z.enum(["git", "bundle"]) }).strict()),
+    snapshots: z.array(text)
+}).strict().refine((value) => value.directory === `/var/lib/spawnfile/recording/${value.slug}`, {
+    message: "Recording directory must match the compiled agent slug"
+});
+/** Optional members preserve S1 records; sync requires the compiled agents member. */
+export const recordingReportSchema = z.object({
+    keep_ms: keepMs,
+    memory_mount_ids: z.array(mountId),
+    recording_mount_ids: z.array(mountId).optional(),
+    agents: z.array(recordingAgentSchema).optional()
+}).strict();