spawnfile 0.1.17 → 0.1.19

package/dist/recording/types.d.ts

@@ -0,0 +1,45 @@
+import type { DeployResources } from "../deployment/index.js";
+import type { FeedLanding } from "../volume/index.js";
+export declare const WAKE_MOMENT_VERSION = "noopolis.daimon.wake-moment.v1";
+export declare const MOMENT_RECORD_VERSION = "spawnfile.moment-record.v1";
+/** The public, data-only row written by Daimon before each turn attempt. */
+export interface WakeMomentRow {
+    version: typeof WAKE_MOMENT_VERSION;
+    agent_id: string;
+    execution_id: string;
+    started_at: string;
+    deliveries: {
+        acceptance_id: string;
+        delivery_id: string;
+        kind: string;
+        occurred_at: string;
+    }[];
+    snapshots: {
+        id: string;
+        snapshot: string;
+        files: number;
+        copied: number;
+        linked: number;
+        skipped: number;
+    }[];
+    error?: string;
+}
+export interface MemoryLedgerEntry {
+    seq: number;
+    createdAt: string;
+}
+export interface MemoryLedgerRead {
+    entries: readonly MemoryLedgerEntry[];
+    errors?: readonly string[];
+}
+export interface ComposeMomentRecordInput {
+    row: WakeMomentRow;
+    agentNodeId: string;
+    deploymentRecordPath: string;
+    feedLandings: Readonly<Record<string, readonly FeedLanding[]>>;
+    deployResources: readonly DeployResources[];
+    memoryLedgers: Readonly<Record<string, MemoryLedgerRead>>;
+    errors?: readonly string[];
+    recordedAt: string;
+}
+export type { MomentRecord } from "./moment.js";

package/dist/recording/types.js

@@ -0,0 +1,2 @@
+export const WAKE_MOMENT_VERSION = "noopolis.daimon.wake-moment.v1";
+export const MOMENT_RECORD_VERSION = "spawnfile.moment-record.v1";

package/dist/release/drainControl.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The running organization's control plane, reached the way every other
+ * Spawnfile probe reaches a container's loopback: an ephemeral helper from the
+ * same image inside the target's network namespace. The bearer token goes to
+ * curl on stdin (`-H @-`), never on a command line another host process could
+ * read.
+ */
+export interface RuntimeControlTarget {
+    containerRef: string;
+    dockerArgs: readonly string[];
+    dockerCommand: string;
+    imageRef: string;
+    token: string;
+}
+export interface ControlResponse {
+    body: string;
+    status: number;
+}
+export type ControlCall = (target: RuntimeControlTarget, method: "GET" | "POST", route: string) => Promise<ControlResponse>;
+export declare const CONTROL_CALL_TIMEOUT_MS = 60000;
+export declare const controlHelperArgs: (target: RuntimeControlTarget, method: "GET" | "POST", route: string) => string[];
+export declare const parseHelperOutput: (stdout: string) => ControlResponse;
+export declare const helperControlCall: ControlCall;
+export type DrainState = "draining" | "drained" | null;
+export interface Availability {
+    drain: DrainState;
+    state: string;
+}
+/** The parts of `noopolis.daimon.work-availability.v1` a release reads. */
+export declare const parseAvailability: (response: ControlResponse, route: string) => Availability;
+export declare const requestDrain: (target: RuntimeControlTarget, call?: ControlCall) => Promise<Availability>;
+export declare const requestResume: (target: RuntimeControlTarget, call?: ControlCall) => Promise<Availability>;
+export interface WaitForDrainedOptions {
+    call?: ControlCall;
+    now?: () => number;
+    pollMs: number;
+    signal?: AbortSignal;
+    sleep?: (ms: number) => Promise<void>;
+    timeoutMs: number;
+}
+export type DrainWait = {
+    drained: true;
+    waitedMs: number;
+} | {
+    drained: false;
+    reason: "interrupted" | "timeout";
+    waitedMs: number;
+};
+/**
+ * Polls until no turn is running or admitted ("drained"), or the bound runs
+ * out. Running turns are never touched: on timeout the caller abandons the
+ * release and resumes; nothing here can stop a turn.
+ */
+export declare const waitForDrained: (target: RuntimeControlTarget, options: WaitForDrainedOptions) => Promise<DrainWait>;

package/dist/release/drainControl.js

@@ -0,0 +1,137 @@
+import { spawn } from "node:child_process";
+import { DAIMON_CONTROL_PORT } from "../runtime/daimon/config.js";
+import { ReleaseError } from "./types.js";
+export const CONTROL_CALL_TIMEOUT_MS = 60_000;
+const MAX_CONTROL_OUTPUT_BYTES = 1024 * 1024;
+export const controlHelperArgs = (target, method, route) => [
+    ...target.dockerArgs,
+    "run", "--rm", "-i", "--pull", "never",
+    "--network", `container:${target.containerRef}`,
+    "--entrypoint", "curl",
+    target.imageRef,
+    "-sS", "--max-time", "15", "-X", method, "-H", "@-",
+    "--output", "-", "--write-out", "\\n%{http_code}",
+    `http://127.0.0.1:${DAIMON_CONTROL_PORT}${route}`
+];
+const redact = (text, token) => (token ? text.split(token).join("[redacted]") : text).replace(/\s+/gu, " ").slice(0, 240);
+export const parseHelperOutput = (stdout) => {
+    const match = /\n(\d{3})$/u.exec(stdout);
+    if (!match || match.index === undefined) {
+        throw new ReleaseError("drain-failed", "the runtime control helper returned no HTTP status");
+    }
+    return { body: stdout.slice(0, match.index), status: Number(match[1]) };
+};
+export const helperControlCall = (target, method, route) => new Promise((resolve, reject) => {
+    const child = spawn(target.dockerCommand, controlHelperArgs(target, method, route), {
+        stdio: ["pipe", "pipe", "pipe"]
+    });
+    const out = [];
+    let bytes = 0;
+    let stderr = "";
+    let settled = false;
+    const finish = (error, value) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        if (error)
+            reject(error);
+        else
+            resolve(value);
+    };
+    const timer = setTimeout(() => {
+        child.kill("SIGKILL");
+        finish(new ReleaseError("drain-failed", `runtime control ${method} ${route} timed out`));
+    }, CONTROL_CALL_TIMEOUT_MS);
+    child.stdout.on("data", (chunk) => {
+        bytes += chunk.length;
+        if (bytes > MAX_CONTROL_OUTPUT_BYTES) {
+            child.kill("SIGKILL");
+            finish(new ReleaseError("drain-failed", `runtime control ${method} ${route} answered more than the output bound`));
+            return;
+        }
+        out.push(chunk);
+    });
+    child.stderr.on("data", (chunk) => { stderr = `${stderr}${chunk.toString("utf8")}`.slice(-2000); });
+    child.once("error", (error) => finish(new ReleaseError("drain-failed", `cannot start the runtime control helper: ${error.message}`)));
+    child.once("close", (code) => {
+        if (code !== 0) {
+            finish(new ReleaseError("drain-failed", `runtime control ${method} ${route} failed (exit ${code ?? "signal"}): ${redact(stderr, target.token)}`));
+            return;
+        }
+        try {
+            finish(null, parseHelperOutput(Buffer.concat(out).toString("utf8")));
+        }
+        catch (error) {
+            finish(error);
+        }
+    });
+    child.stdin.on("error", () => undefined);
+    child.stdin.end(`Authorization: Bearer ${target.token}\n`);
+});
+/** The parts of `noopolis.daimon.work-availability.v1` a release reads. */
+export const parseAvailability = (response, route) => {
+    if (response.status === 404) {
+        throw new ReleaseError("drain-failed", `the running runtime has no ${route} control route; it predates reversible drain, so it cannot be released without killing turns`);
+    }
+    if (response.status === 401) {
+        throw new ReleaseError("drain-failed", `the runtime refused the control token on ${route}; SPAWNFILE_DAIMON_CONTROL_TOKEN in the env file must be the running deployment's token`);
+    }
+    if (response.status !== 200) {
+        throw new ReleaseError("drain-failed", `runtime control ${route} answered HTTP ${response.status}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(response.body);
+    }
+    catch {
+        throw new ReleaseError("drain-failed", `runtime control ${route} answered invalid JSON`);
+    }
+    const document = parsed;
+    if (document?.version !== "noopolis.daimon.work-availability.v1" || typeof document.state !== "string") {
+        throw new ReleaseError("drain-failed", `runtime control ${route} answered something other than a work-availability document`);
+    }
+    const drain = document.drain === undefined ? null : document.drain.state;
+    if (drain !== null && drain !== "draining" && drain !== "drained") {
+        throw new ReleaseError("drain-failed", `runtime control ${route} reported an unknown drain state`);
+    }
+    return { drain, state: document.state };
+};
+export const requestDrain = async (target, call = helperControlCall) => {
+    const availability = parseAvailability(await call(target, "POST", "/v2/drain"), "/v2/drain");
+    if (availability.drain === null) {
+        throw new ReleaseError("drain-failed", "the runtime accepted /v2/drain but does not report a drain; refusing to deploy over turns it may still admit");
+    }
+    return availability;
+};
+export const requestResume = async (target, call = helperControlCall) => {
+    const availability = parseAvailability(await call(target, "POST", "/v2/resume"), "/v2/resume");
+    if (availability.drain !== null) {
+        throw new ReleaseError("resume-failed", "the runtime answered /v2/resume but still reports a drain");
+    }
+    return availability;
+};
+/**
+ * Polls until no turn is running or admitted ("drained"), or the bound runs
+ * out. Running turns are never touched: on timeout the caller abandons the
+ * release and resumes; nothing here can stop a turn.
+ */
+export const waitForDrained = async (target, options) => {
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const started = now();
+    for (;;) {
+        if (options.signal?.aborted)
+            return { drained: false, reason: "interrupted", waitedMs: now() - started };
+        const availability = parseAvailability(await (options.call ?? helperControlCall)(target, "GET", "/v2/availability"), "/v2/availability");
+        if (availability.drain === null) {
+            throw new ReleaseError("drain-failed", "the runtime stopped reporting the drain while a release was waiting on it (did it restart?)");
+        }
+        if (availability.drain === "drained")
+            return { drained: true, waitedMs: now() - started };
+        const remaining = options.timeoutMs - (now() - started);
+        if (remaining <= 0)
+            return { drained: false, reason: "timeout", waitedMs: now() - started };
+        await sleep(Math.min(options.pollMs, remaining));
+    }
+};

package/dist/release/drainPhase.d.ts

@@ -0,0 +1,37 @@
+import type { DockerDeploymentTarget } from "../deployment/index.js";
+import type { RuntimeControlTarget } from "./drainControl.js";
+import { type ReleasePaths } from "./ledger.js";
+import type { RunningUnit } from "./releaseDocker.js";
+import { type ReleaseDependencies, type ReleaseRequest } from "./releaseTypes.js";
+export declare const RELEASE_DRAIN_MARKER_VERSION: "spawnfile.release-drain.v1";
+/** Same precedence `up` applies: a process value overrides the env file. */
+export declare const resolveControlToken: (request: ReleaseRequest) => string | null;
+export declare const controlTargetFor: (request: ReleaseRequest, containerRef: string, imageRef: string) => RuntimeControlTarget;
+/** The same request, addressed at exactly this Docker daemon. */
+export declare const requestForTarget: (request: ReleaseRequest, target: DockerDeploymentTarget) => ReleaseRequest;
+export declare const clearDrainMarker: (paths: ReleasePaths) => Promise<void>;
+export declare const recoverInterruptedDrain: (request: ReleaseRequest, deps: ReleaseDependencies, paths: ReleasePaths) => Promise<boolean>;
+export type DrainOutcome = {
+    drainMs: number;
+    kind: "drained";
+} | {
+    drainMs: number;
+    kind: "skipped";
+} | {
+    drainMs: number;
+    kind: "timeout";
+};
+/**
+ * Admission pauses, queued wakes stay queued, running turns finish. On a
+ * timeout or interruption the release is abandoned and admission resumed:
+ * nothing in this module, or anything it calls, stops a turn.
+ */
+export declare const drainForRelease: (request: ReleaseRequest, deps: ReleaseDependencies, paths: ReleasePaths, unit: RunningUnit | null) => Promise<DrainOutcome>;
+/** Resumes a container this release drained, keeping the marker if that fails. */
+export declare const resumeDrained: (request: ReleaseRequest, deps: ReleaseDependencies, paths: ReleasePaths, unit: RunningUnit) => Promise<void>;
+/**
+ * After a failed deploy, whatever container now holds the name is either the
+ * restored previous one (restarted, so it admits) or the original, still
+ * drained because the deploy failed before touching it. Resume either way.
+ */
+export declare const resumeAfterFailedDeploy: (request: ReleaseRequest, deps: ReleaseDependencies, paths: ReleasePaths, containerName: string) => Promise<void>;

package/dist/release/drainPhase.js

@@ -0,0 +1,161 @@
+import { readFile, rm } from "node:fs/promises";
+import { resolveDockerBaseArgs } from "../distribution/index.js";
+import { writeJsonAtomic } from "./ledger.js";
+import { DAIMON_CONTROL_TOKEN_ENV } from "./releaseTypes.js";
+import { ReleaseError } from "./types.js";
+export const RELEASE_DRAIN_MARKER_VERSION = "spawnfile.release-drain.v1";
+/** Same precedence `up` applies: a process value overrides the env file. */
+export const resolveControlToken = (request) => {
+    const fromProcess = process.env[DAIMON_CONTROL_TOKEN_ENV];
+    if (typeof fromProcess === "string" && fromProcess.length > 0)
+        return fromProcess;
+    const fromFile = request.envFileEnv[DAIMON_CONTROL_TOKEN_ENV];
+    return typeof fromFile === "string" && fromFile.length > 0 ? fromFile : null;
+};
+export const controlTargetFor = (request, containerRef, imageRef) => {
+    const token = resolveControlToken(request);
+    if (token === 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`);
+    }
+    return {
+        containerRef,
+        dockerArgs: resolveDockerBaseArgs({ ...(request.dockerContext ? { dockerContext: request.dockerContext } : {}), ...(request.dockerHost ? { dockerHost: request.dockerHost } : {}) }),
+        dockerCommand: request.dockerCommand,
+        imageRef,
+        token
+    };
+};
+/**
+ * Written BEFORE the drain request and removed only once admission is open
+ * again, so a release killed in between (a unit timeout, a reboot) leaves
+ * evidence that the organization may still be refusing work. Every later run
+ * resumes it first, even when it has nothing to release.
+ */
+const writeMarker = async (request, paths, unit) => {
+    const target = request.target;
+    if (target === undefined)
+        throw new ReleaseError("blocked", "the release has no pinned Docker target to record with its drain");
+    const marker = { container: unit.id, image: unit.imageId, since: new Date().toISOString(), target, version: RELEASE_DRAIN_MARKER_VERSION };
+    await writeJsonAtomic(paths.drainMarker, marker);
+};
+/** The same request, addressed at exactly this Docker daemon. */
+export const requestForTarget = (request, target) => {
+    const { dockerContext: _context, dockerHost: _host, ...rest } = request;
+    if (target.kind === "host")
+        return { ...rest, dockerHost: target.value, target };
+    return { ...rest, dockerContext: target.kind === "context" ? target.name : target.context, target };
+};
+export const clearDrainMarker = async (paths) => {
+    await rm(paths.drainMarker, { force: true });
+};
+export const recoverInterruptedDrain = async (request, deps, paths) => {
+    let marker;
+    try {
+        marker = JSON.parse(await readFile(paths.drainMarker, "utf8"));
+        if (typeof marker.container !== "string" || typeof marker.target?.kind !== "string")
+            throw new Error("shape");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw new ReleaseError("resume-failed", `the drain marker ${paths.drainMarker} is unreadable; the organization may still be drained`);
+    }
+    // Recovery talks to the Docker daemon the drain went out through, whatever this run was invoked with,
+    // and refuses (keeping the marker) when that name now resolves to a different endpoint.
+    const target = requestForTarget(request, marker.target);
+    let unit;
+    try {
+        await deps.verifyTarget(target, marker.target);
+        unit = await deps.inspectUnit(target, marker.container);
+    }
+    catch (error) {
+        throw new ReleaseError("resume-failed", `an earlier release may have left the organization drained and its container cannot be inspected: ${error.message}`);
+    }
+    if (unit === null || !unit.running) {
+        // A drain lives in the runtime process: a container that is gone or stopped admits again when it next starts.
+        await clearDrainMarker(paths);
+        return true;
+    }
+    try {
+        await deps.requestResume(controlTargetFor(target, unit.id, unit.imageId));
+    }
+    catch (error) {
+        throw new ReleaseError("resume-failed", `an earlier release left the organization drained and resuming it failed: ${error.message}`);
+    }
+    await clearDrainMarker(paths);
+    request.log("release: resumed admission left drained by an interrupted release");
+    return true;
+};
+/**
+ * Admission pauses, queued wakes stay queued, running turns finish. On a
+ * timeout or interruption the release is abandoned and admission resumed:
+ * nothing in this module, or anything it calls, stops a turn.
+ */
+export const drainForRelease = async (request, deps, paths, unit) => {
+    if (!request.drain) {
+        request.log("release: --no-drain: deploying without draining; in-flight turns will be killed");
+        return { drainMs: 0, kind: "skipped" };
+    }
+    if (unit === null || !unit.running) {
+        request.log("release: no running container, so no turn can be in flight; nothing to drain");
+        return { drainMs: 0, kind: "skipped" };
+    }
+    const target = controlTargetFor(request, unit.id, unit.imageId);
+    const started = Date.now();
+    await writeMarker(request, paths, unit);
+    try {
+        await deps.requestDrain(target);
+        request.log(`release: admission paused; waiting up to ${Math.round(request.drainTimeoutMs / 1000)}s for running turns to finish`);
+        const waited = await deps.waitForDrained(target, {
+            pollMs: request.drainPollMs,
+            ...(request.signal ? { signal: request.signal } : {}),
+            timeoutMs: request.drainTimeoutMs
+        });
+        if (waited.drained && !request.signal?.aborted) {
+            request.log(`release: drained after ${Math.round(waited.waitedMs / 1000)}s`);
+            return { drainMs: Date.now() - started, kind: "drained" };
+        }
+        await resumeOrThrow(request, deps, paths, target);
+        if (waited.drained || waited.reason === "interrupted")
+            throw new ReleaseError("interrupted", "the release was interrupted while waiting for running turns; admission resumed, nothing deployed");
+        return { drainMs: Date.now() - started, kind: "timeout" };
+    }
+    catch (error) {
+        if (error instanceof ReleaseError && (error.reason === "interrupted" || error.reason === "resume-failed"))
+            throw error;
+        await resumeOrThrow(request, deps, paths, target);
+        throw error instanceof ReleaseError ? error : new ReleaseError("drain-failed", error.message);
+    }
+};
+/** Resumes a container this release drained, keeping the marker if that fails. */
+export const resumeDrained = async (request, deps, paths, unit) => resumeOrThrow(request, deps, paths, controlTargetFor(request, unit.id, unit.imageId));
+const resumeOrThrow = async (request, deps, paths, target) => {
+    try {
+        await deps.requestResume(target);
+    }
+    catch (error) {
+        throw new ReleaseError("resume-failed", `admission could not be resumed after abandoning the release; the organization is refusing new work: ${error.message}`);
+    }
+    await clearDrainMarker(paths);
+    request.log("release: admission resumed");
+};
+/**
+ * After a failed deploy, whatever container now holds the name is either the
+ * restored previous one (restarted, so it admits) or the original, still
+ * drained because the deploy failed before touching it. Resume either way.
+ */
+export const resumeAfterFailedDeploy = async (request, deps, paths, containerName) => {
+    let unit;
+    try {
+        unit = await deps.inspectUnit(request, containerName);
+    }
+    catch (error) {
+        // Not "absent": the marker stays, so the next run resumes it.
+        throw new ReleaseError("resume-failed", `the deploy failed and the container cannot be inspected to resume admission: ${error.message}`);
+    }
+    if (unit === null || !unit.running) {
+        await clearDrainMarker(paths);
+        return;
+    }
+    await resumeOrThrow(request, deps, paths, controlTargetFor(request, unit.id, unit.imageId));
+};

package/dist/release/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./drainControl.js";
+export * from "./drainPhase.js";
+export * from "./ledger.js";
+export * from "./notify.js";
+export * from "./pending.js";
+export * from "./postDeploy.js";
+export * from "./releaseDefaults.js";
+export * from "./releaseDocker.js";
+export * from "./releaseTypes.js";
+export * from "./runRelease.js";
+export * from "./types.js";

package/dist/release/index.js

@@ -0,0 +1,11 @@
+export * from "./drainControl.js";
+export * from "./drainPhase.js";
+export * from "./ledger.js";
+export * from "./notify.js";
+export * from "./pending.js";
+export * from "./postDeploy.js";
+export * from "./releaseDefaults.js";
+export * from "./releaseDocker.js";
+export * from "./releaseTypes.js";
+export * from "./runRelease.js";
+export * from "./types.js";

package/dist/release/ledger.d.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { type PidLockHooks } from "../deployment/index.js";
+export declare const RELEASE_LEDGER_VERSION: "spawnfile.release-ledger.v1";
+export declare const RELEASE_LOG_VERSION: "spawnfile.release-log.v1";
+declare const timings: z.ZodObject<{
+    build_ms: z.ZodNullable<z.ZodNumber>;
+    compile_ms: z.ZodNumber;
+    deploy_ms: z.ZodNullable<z.ZodNumber>;
+    drain_ms: z.ZodNullable<z.ZodNumber>;
+    total_ms: z.ZodNumber;
+}, z.core.$strict>;
+/** What is running, as the last successful release recorded it. */
+export declare const releaseLedgerSchema: z.ZodObject<{
+    compile_fingerprint: z.ZodString;
+    deployment: z.ZodString;
+    identity: z.ZodString;
+    image_id: z.ZodString;
+    image_tag: z.ZodString;
+    previous_image_tag: z.ZodNullable<z.ZodString>;
+    released_at: z.ZodString;
+    timings: z.ZodObject<{
+        build_ms: z.ZodNullable<z.ZodNumber>;
+        compile_ms: z.ZodNumber;
+        deploy_ms: z.ZodNullable<z.ZodNumber>;
+        drain_ms: z.ZodNullable<z.ZodNumber>;
+        total_ms: z.ZodNumber;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<"spawnfile.release-ledger.v1">;
+}, z.core.$strict>;
+export type ReleaseLedger = z.infer<typeof releaseLedgerSchema>;
+export interface ReleaseLogEntry {
+    at: string;
+    deployment: string;
+    identity: string | null;
+    image_tag?: string;
+    message?: string;
+    notified?: {
+        channel: "command" | "webhook" | "none";
+        delivered: boolean;
+        error?: string;
+    };
+    outcome: "deferred" | "failed" | "notified" | "released";
+    reason?: string;
+    timings?: z.infer<typeof timings>;
+    version: typeof RELEASE_LOG_VERSION;
+}
+export interface ReleasePaths {
+    directory: string;
+    drainMarker: string;
+    ledger: string;
+    lock: string;
+    log: string;
+    pending: string;
+    /** Present from just before a post-deploy command runs until the ledger records its success. */
+    postDeploy: string;
+}
+export declare const resolveReleasePaths: (deployment: string, root?: string) => ReleasePaths;
+export declare const ensureReleaseDirectory: (paths: ReleasePaths) => Promise<void>;
+/**
+ * A missing ledger means nothing has been released into this deployment yet,
+ * which is a full release. A ledger that exists and cannot be read means this
+ * command does not know what is running, and it must not deploy: it could not
+ * write the record the next run depends on either. Unreadable is a refusal,
+ * never an assumed-stale.
+ */
+export declare const readReleaseLedger: (file: string) => Promise<ReleaseLedger | null>;
+/** Anything but "definitely absent" counts as present: an unknown marker never reads as done. */
+export declare const postDeployPending: (file: string) => Promise<boolean>;
+/** Same-directory temp file + rename, so a reader sees the old record or the new one. */
+export declare const writeJsonAtomic: (file: string, value: unknown) => Promise<void>;
+export declare const writeReleaseLedger: (file: string, ledger: ReleaseLedger) => Promise<void>;
+export declare const appendReleaseLog: (file: string, entry: Omit<ReleaseLogEntry, "version">) => Promise<void>;
+/** One release per deployment at a time; see `acquirePidLock` for the guarantees and the residual. */
+export declare const acquireReleaseLock: (paths: ReleasePaths, hooks?: PidLockHooks) => Promise<() => Promise<void>>;
+export {};

package/dist/release/ledger.js

@@ -0,0 +1,111 @@
+import { randomUUID } from "node:crypto";
+import { appendFile, chmod, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { resolveSpawnfileHome } from "../auth/index.js";
+import { acquirePidLock, normalizeDeploymentName, PidLockBusyError } from "../deployment/index.js";
+import { ReleaseError } from "./types.js";
+export const RELEASE_LEDGER_VERSION = "spawnfile.release-ledger.v1";
+export const RELEASE_LOG_VERSION = "spawnfile.release-log.v1";
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/u);
+const timings = z.object({
+    build_ms: z.number().nonnegative().nullable(),
+    compile_ms: z.number().nonnegative(),
+    deploy_ms: z.number().nonnegative().nullable(),
+    drain_ms: z.number().nonnegative().nullable(),
+    total_ms: z.number().nonnegative()
+}).strict();
+/** What is running, as the last successful release recorded it. */
+export const releaseLedgerSchema = z.object({
+    compile_fingerprint: z.string().min(1),
+    deployment: z.string().min(1),
+    identity: digest,
+    image_id: z.string().min(1),
+    image_tag: z.string().min(1),
+    previous_image_tag: z.string().min(1).nullable(),
+    released_at: z.string().min(1),
+    timings,
+    version: z.literal(RELEASE_LEDGER_VERSION)
+}).strict();
+export const resolveReleasePaths = (deployment, root) => {
+    const directory = path.join(root ?? path.join(resolveSpawnfileHome(), "releases"), normalizeDeploymentName(deployment));
+    return {
+        directory,
+        drainMarker: path.join(directory, "drain.json"),
+        ledger: path.join(directory, "ledger.json"),
+        lock: path.join(directory, ".lock"),
+        log: path.join(directory, "log.jsonl"),
+        pending: path.join(directory, "pending.json"),
+        postDeploy: path.join(directory, "post-deploy.json")
+    };
+};
+export const ensureReleaseDirectory = async (paths) => {
+    await mkdir(paths.directory, { mode: 0o700, recursive: true });
+    await chmod(paths.directory, 0o700);
+};
+/**
+ * A missing ledger means nothing has been released into this deployment yet,
+ * which is a full release. A ledger that exists and cannot be read means this
+ * command does not know what is running, and it must not deploy: it could not
+ * write the record the next run depends on either. Unreadable is a refusal,
+ * never an assumed-stale.
+ */
+export const readReleaseLedger = async (file) => {
+    let source;
+    try {
+        source = await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw new ReleaseError("blocked", `cannot read the release ledger ${file}: ${error.message}`);
+    }
+    try {
+        return releaseLedgerSchema.parse(JSON.parse(source));
+    }
+    catch {
+        throw new ReleaseError("blocked", `the release ledger ${file} is not a ${RELEASE_LEDGER_VERSION} record; refusing to release against a ledger this command cannot read`);
+    }
+};
+/** Anything but "definitely absent" counts as present: an unknown marker never reads as done. */
+export const postDeployPending = async (file) => {
+    try {
+        await stat(file);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ENOENT";
+    }
+};
+/** Same-directory temp file + rename, so a reader sees the old record or the new one. */
+export const writeJsonAtomic = async (file, value) => {
+    const scratch = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(scratch, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+        await rename(scratch, file);
+    }
+    catch (error) {
+        await rm(scratch, { force: true }).catch(() => undefined);
+        throw error;
+    }
+};
+export const writeReleaseLedger = async (file, ledger) => {
+    await writeJsonAtomic(file, releaseLedgerSchema.parse(ledger));
+};
+export const appendReleaseLog = async (file, entry) => {
+    await appendFile(file, `${JSON.stringify({ ...entry, version: RELEASE_LOG_VERSION })}\n`, { encoding: "utf8", mode: 0o600 });
+};
+/** One release per deployment at a time; see `acquirePidLock` for the guarantees and the residual. */
+export const acquireReleaseLock = async (paths, hooks = {}) => {
+    try {
+        return await acquirePidLock(paths.lock, hooks);
+    }
+    catch (error) {
+        if (error instanceof PidLockBusyError) {
+            throw new ReleaseError("blocked", error.ownerPid === null
+                ? "another release of this deployment took the lock first"
+                : `another release of this deployment is running (pid ${error.ownerPid})`);
+        }
+        throw error;
+    }
+};