spawnfile 0.1.12 → 0.1.14

package/dist/deployment/artifactsExportDocker.d.ts

@@ -0,0 +1,48 @@
+import type { DeploymentRecord } from "./record.js";
+/** Same injectable exec shape as `dockerInspect.ts`/`dockerLogs.ts` — real Docker calls
+ * are the default, tests inject a fake. */
+export type DockerArtifactExecFile = (file: string, args: string[], options: {
+    timeout: number;
+}) => Promise<{
+    stderr: string;
+    stdout: string;
+}>;
+export interface DockerRunnerOptions {
+    dockerCommand: string;
+    execFile: DockerArtifactExecFile;
+    timeoutMs: number;
+}
+/**
+ * True when `containerRef` (an id or name) still exists in Docker, false when Docker
+ * reports it missing (a stopped-and-removed container, or one never created). Any other
+ * Docker failure (daemon unreachable, context misconfigured, ...) is re-thrown rather than
+ * folded into "missing" — export-before-teardown detection must not misreport a genuine
+ * Docker connectivity problem as "this deployment was already torn down".
+ */
+export declare const containerExists: (target: DeploymentRecord["target"], containerRef: string, options: DockerRunnerOptions) => Promise<boolean>;
+/** `docker cp <containerRef>:<containerPath> <hostPath>` — best-effort, returns false
+ * instead of throwing (a single missing file inside an otherwise-live container is a
+ * per-file concern, handled by the caller via each planned file's `optional` flag). */
+export declare const copyContainerFileToHost: (input: {
+    containerPath: string;
+    containerRef: string;
+    hostPath: string;
+    target: DeploymentRecord["target"];
+} & DockerRunnerOptions) => Promise<boolean>;
+/**
+ * Reads one file out of a named Docker volume without needing the volume's original
+ * container: creates a throwaway container (never started — its own entrypoint never
+ * runs) with the volume read-only mounted, `docker cp`s the single file out, then always
+ * removes the throwaway container. `readerImage` is expected to be an image already
+ * present locally (the deployment's own `unit.image_tag` is the natural choice — it is
+ * guaranteed to exist wherever the deployment itself ran, so this never needs to pull a
+ * new "tiny image" from a registry).
+ */
+export declare const copyVolumeFileToHost: (input: {
+    hostPath: string;
+    readerImage: string;
+    target: DeploymentRecord["target"];
+    volumeName: string;
+    volumePath: string;
+} & DockerRunnerOptions) => Promise<boolean>;
+export declare const defaultDockerArtifactExecFile: DockerArtifactExecFile;

package/dist/deployment/artifactsExportDocker.js

@@ -0,0 +1,91 @@
+import { randomUUID } from "node:crypto";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { dockerContextNameForTarget } from "./target.js";
+const execFile = promisify(execFileCallback);
+const withDockerTarget = (target, args) => {
+    const context = dockerContextNameForTarget(target);
+    if (context) {
+        return ["--context", context, ...args];
+    }
+    if (target.kind === "host") {
+        return ["--host", target.value, ...args];
+    }
+    return args;
+};
+const toErrorMessage = (error) => {
+    if (typeof error === "object" && error !== null && "stderr" in error) {
+        const stderr = error.stderr;
+        if (typeof stderr === "string" && stderr.length > 0) {
+            return stderr.trim();
+        }
+    }
+    return error instanceof Error ? error.message : String(error);
+};
+/**
+ * True when `containerRef` (an id or name) still exists in Docker, false when Docker
+ * reports it missing (a stopped-and-removed container, or one never created). Any other
+ * Docker failure (daemon unreachable, context misconfigured, ...) is re-thrown rather than
+ * folded into "missing" — export-before-teardown detection must not misreport a genuine
+ * Docker connectivity problem as "this deployment was already torn down".
+ */
+export const containerExists = async (target, containerRef, options) => {
+    try {
+        await options.execFile(options.dockerCommand, withDockerTarget(target, ["inspect", "--type", "container", containerRef]), { timeout: options.timeoutMs });
+        return true;
+    }
+    catch (error) {
+        const message = toErrorMessage(error);
+        if (/No such (?:object|container)/i.test(message)) {
+            return false;
+        }
+        throw new Error(`Unable to check whether container "${containerRef}" exists: ${message}`);
+    }
+};
+/** `docker cp <containerRef>:<containerPath> <hostPath>` — best-effort, returns false
+ * instead of throwing (a single missing file inside an otherwise-live container is a
+ * per-file concern, handled by the caller via each planned file's `optional` flag). */
+export const copyContainerFileToHost = async (input) => {
+    try {
+        await input.execFile(input.dockerCommand, withDockerTarget(input.target, ["cp", `${input.containerRef}:${input.containerPath}`, input.hostPath]), { timeout: input.timeoutMs });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Reads one file out of a named Docker volume without needing the volume's original
+ * container: creates a throwaway container (never started — its own entrypoint never
+ * runs) with the volume read-only mounted, `docker cp`s the single file out, then always
+ * removes the throwaway container. `readerImage` is expected to be an image already
+ * present locally (the deployment's own `unit.image_tag` is the natural choice — it is
+ * guaranteed to exist wherever the deployment itself ran, so this never needs to pull a
+ * new "tiny image" from a registry).
+ */
+export const copyVolumeFileToHost = async (input) => {
+    const mountPoint = "/spawnfile-export-src";
+    const readerContainerName = `spawnfile-artifacts-export-${randomUUID()}`;
+    try {
+        await input.execFile(input.dockerCommand, withDockerTarget(input.target, [
+            "create",
+            "--name", readerContainerName,
+            "-v", `${input.volumeName}:${mountPoint}:ro`,
+            input.readerImage
+        ]), { timeout: input.timeoutMs });
+    }
+    catch {
+        return false;
+    }
+    try {
+        await input.execFile(input.dockerCommand, withDockerTarget(input.target, ["cp", `${readerContainerName}:${mountPoint}/${input.volumePath}`, input.hostPath]), { timeout: input.timeoutMs });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await input.execFile(input.dockerCommand, withDockerTarget(input.target, ["rm", "-f", readerContainerName]), { timeout: input.timeoutMs }).catch(() => undefined);
+    }
+};
+export const defaultDockerArtifactExecFile = execFile;

package/dist/deployment/artifactsExportPlan.d.ts

@@ -0,0 +1,24 @@
+import type { CompileReport } from "../report/index.js";
+/** One durable-artifact file `spawnfile artifacts export` egresses, and where it lands
+ * under `<out>` (Decision 21 §2 run-dir layout). Pure planning data — no Docker/IO here;
+ * `artifactsExport.ts` executes each plan entry and `artifactsExportDocker.ts` knows how. */
+export interface PlannedExportFile {
+    /** Path relative to the export destination directory, e.g. "raw/moltnet/causal.jsonl". */
+    relativePath: string;
+    source: {
+        kind: "volume";
+        volumeName: string;
+        volumePath: string;
+    } | {
+        kind: "container";
+        containerPath: string;
+    };
+    /** True when the file may legitimately be absent (e.g. a bank's causal.jsonl before any
+     * recall event, or events.jsonl before any memory write) — a missing optional file is a
+     * silent skip, never a diagnostic. Non-optional sources missing is worth flagging. */
+    optional: boolean;
+}
+/** Resolves every durable artifact file this run's compile report declares, and where each
+ * one is read from. Pure function of the compile report alone (no deployment record, no
+ * Docker) — `artifactsExport.ts` supplies the live container name at execution time. */
+export declare const planArtifactExports: (report: CompileReport) => PlannedExportFile[];

package/dist/deployment/artifactsExportPlan.js

@@ -0,0 +1,135 @@
+import path from "node:path/posix";
+const AGENT_NODE_ID_PREFIX = "agent:";
+const TEAM_NODE_ID_PREFIX = "team:";
+/** Strips the compiler's `agent:` node-id prefix down to the generated runtime slug, the
+ * same convention `src/e2e/moltnetMemeticsArtifacts.ts`'s `agentSlugFromNodeId` uses (kept
+ * as a local copy here rather than an import: compiler/deployment code must not depend on
+ * `src/e2e`, per that folder's own charter — e2e depends on compiler, never the reverse). */
+const agentSlugFromNodeId = (nodeId) => {
+    if (nodeId.startsWith(AGENT_NODE_ID_PREFIX)) {
+        return nodeId.slice(AGENT_NODE_ID_PREFIX.length);
+    }
+    return nodeId.startsWith(TEAM_NODE_ID_PREFIX) ? null : nodeId;
+};
+const mountById = (mounts) => new Map((mounts ?? []).map((mount) => [mount.id, mount]));
+/** Moltnet: one `causal.jsonl` and one `transcript.json` per managed network, always
+ * mounted at the causal directory's own root (see `moltnetArtifacts.ts`'s
+ * `createMoltnetCausalDirectory` — the mount path IS the directory the event file lives
+ * directly under). A single managed network exports to the flat `raw/moltnet/causal.jsonl`;
+ * more than one disambiguates by network id under `raw/moltnet/<network_id>/causal.jsonl`.
+ *
+ * The transcript rides the SAME mount deliberately: the causal log records only
+ * `content_sha256`, so the transcript's text is verified against the log sitting beside it
+ * rather than trusted on its own. See moltnet's `internal/observability/transcript.go` for
+ * why that volume now holds message bodies and what its attestation does and does not
+ * cover. */
+const planMoltnetFiles = (report, mounts) => {
+    const managedNetworkIds = (report.container?.moltnet?.server_plans ?? [])
+        .filter((serverPlan) => serverPlan.mode === "managed")
+        .map((serverPlan) => serverPlan.network_id);
+    const resolved = managedNetworkIds
+        .map((networkId) => ({ mount: mounts.get(`moltnet-${networkId}-causal`), networkId }))
+        .filter((entry) => entry.mount !== undefined);
+    const singleNetwork = resolved.length === 1;
+    return resolved.flatMap(({ mount, networkId }) => [{
+            // A managed network that received zero room messages has no causal.jsonl yet — no
+            // room activity is a legitimate (if unusual) state, not an export failure.
+            optional: true,
+            relativePath: singleNetwork
+                ? "raw/moltnet/causal.jsonl"
+                : `raw/moltnet/${networkId}/causal.jsonl`,
+            source: { kind: "volume", volumeName: mount.volume_name, volumePath: "causal.jsonl" }
+        }, {
+            // Optional for the same reason: a network with zero accepted messages has no
+            // transcript yet.
+            optional: true,
+            relativePath: singleNetwork
+                ? "raw/moltnet/transcript.json"
+                : `raw/moltnet/${networkId}/transcript.json`,
+            source: { kind: "volume", volumeName: mount.volume_name, volumePath: "transcript.json" }
+        }]);
+};
+/** Mneme: each durable (json/sqlite-backed) bank writes its append-only ledger
+ * (`events.jsonl`) and causal stream (`causal.jsonl`) into a `memory/` subdirectory of its
+ * own mount root — not the mount root itself (verified live; see
+ * `ecosystem/mneme/src/store/store.ts`'s `JsonlMemoryStore` and `causalStore.ts`'s
+ * `CausalEventStore`, both keyed off the same `<runtimeHomePath>/memory` dir, where
+ * `runtimeHomePath` is exactly this mount's path). Both files are optional: a bank with no
+ * recall yet has no causal.jsonl, and one with no writes yet has no events.jsonl. */
+const planMnemeFiles = (report, mounts) => (report.container?.memory ?? []).flatMap((bank) => {
+    const mountId = bank.store.persistent_mount_id;
+    const mount = mountId ? mounts.get(mountId) : undefined;
+    if (!mount) {
+        return [];
+    }
+    return ["causal.jsonl", "events.jsonl"].map((fileName) => ({
+        optional: true,
+        relativePath: `raw/mneme/${bank.id}/${fileName}`,
+        source: {
+            kind: "volume",
+            volumeName: mount.volume_name,
+            volumePath: `memory/${fileName}`
+        }
+    }));
+});
+/** Daimon: per pi/daimon runtime instance, per agent it covers, the turn-causal telemetry
+ * stream at `runtime/agents/<slug>/telemetry/causal.jsonl` under the instance root (see
+ * `ecosystem/daimon/src/observability/causalEvents.ts`). As of Piece 4b, that directory is
+ * a run-scoped durable volume (`daimonTelemetryArtifacts.ts`, mirroring how
+ * `moltnetArtifacts.ts` mounts the Moltnet causal directory), resolved here via each
+ * instance's `telemetry_mount_ids` (node id -> persistent mount id). This is the real
+ * relaxation of the export-before-teardown invariant (Decision 21) for daimon truth:
+ * `spawnfile down` (without `--volumes`) can run BEFORE `spawnfile artifacts export`, and
+ * export still recovers every agent's causal.jsonl from its named volume.
+ *
+ * The `instance.home_path`-keyed branch below is a legacy fallback for a compile report
+ * written before Piece 4b (no `telemetry_mount_ids` yet) — it reads the old container-local
+ * path with `docker cp`, which only works while the container is still live. Any report
+ * produced by this compiler build always populates `telemetry_mount_ids` for a pi/daimon
+ * instance, so that branch never fires today; it exists only so an out-of-date report
+ * doesn't silently export zero daimon files. Optional either way: a fresh instance that
+ * never woke has no telemetry file yet. */
+const planDaimonFiles = (report, mounts) => (report.container?.runtime_instances ?? [])
+    .filter((instance) => instance.runtime === "pi" || instance.runtime === "daimon")
+    .flatMap((instance) => (instance.node_ids ?? []).flatMap((nodeId) => {
+    const slug = agentSlugFromNodeId(nodeId);
+    if (!slug) {
+        return [];
+    }
+    const mountId = instance.telemetry_mount_ids?.[nodeId];
+    const mount = mountId ? mounts.get(mountId) : undefined;
+    if (mount) {
+        return [{
+                optional: true,
+                relativePath: `raw/daimon/${slug}/causal.jsonl`,
+                source: {
+                    kind: "volume",
+                    volumeName: mount.volume_name,
+                    volumePath: "causal.jsonl"
+                }
+            }];
+    }
+    if (!instance.home_path) {
+        return [];
+    }
+    const instanceRoot = path.dirname(instance.home_path);
+    return [{
+            optional: true,
+            relativePath: `raw/daimon/${slug}/causal.jsonl`,
+            source: {
+                kind: "container",
+                containerPath: `${instanceRoot}/runtime/agents/${slug}/telemetry/causal.jsonl`
+            }
+        }];
+}));
+/** Resolves every durable artifact file this run's compile report declares, and where each
+ * one is read from. Pure function of the compile report alone (no deployment record, no
+ * Docker) — `artifactsExport.ts` supplies the live container name at execution time. */
+export const planArtifactExports = (report) => {
+    const mounts = mountById(report.container?.persistent_mounts);
+    return [
+        ...planMoltnetFiles(report, mounts),
+        ...planMnemeFiles(report, mounts),
+        ...planDaimonFiles(report, mounts)
+    ];
+};

package/dist/deployment/artifactsExportTypes.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+/**
+ * `spawnfile.export-index.v1` — the machine contract `spawnfile artifacts
+ * export` writes at `<out>/spawnfile/export-index.json` (contracts.md's
+ * Spawnfile export-index registry row; Decision 21's Piece 3). It is the
+ * only artifact `simfile observe` needs from spawnfile beyond the raw files
+ * themselves: a manifest of what was exported, from where, and its content
+ * hash, so a future `simfile.run-manifest.v1` can fold `files` straight into
+ * its own `artifacts` array (same `{path, sha256}` shape — see
+ * `ecosystem/simfile/src/observe/manifest.ts`) without re-deriving anything.
+ *
+ * `sha256` is a bare 64-character lowercase hex digest (no `sha256:`
+ * prefix), matching `simfile.run-manifest.v1`'s `artifacts[].sha256` exactly
+ * — this is deliberate so folding this index into that manifest is a
+ * straight copy, never a reformat.
+ */
+export declare const EXPORT_INDEX_VERSION: "spawnfile.export-index.v1";
+declare const exportSourceSchema: z.ZodObject<{
+    kind: z.ZodUnion<readonly [z.ZodLiteral<"volume">, z.ZodLiteral<"container">]>;
+    ref: z.ZodString;
+}, z.core.$strict>;
+export type ExportIndexSource = z.infer<typeof exportSourceSchema>;
+declare const exportIndexFileSchema: z.ZodObject<{
+    path: z.ZodString;
+    sha256: z.ZodString;
+    bytes: z.ZodNumber;
+    source: z.ZodObject<{
+        kind: z.ZodUnion<readonly [z.ZodLiteral<"volume">, z.ZodLiteral<"container">]>;
+        ref: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ExportIndexFile = z.infer<typeof exportIndexFileSchema>;
+export declare const exportIndexSchema: z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.export-index.v1">;
+    run_id: z.ZodString;
+    deployment: z.ZodString;
+    exported_at: z.ZodString;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        sha256: z.ZodString;
+        bytes: z.ZodNumber;
+        source: z.ZodObject<{
+            kind: z.ZodUnion<readonly [z.ZodLiteral<"volume">, z.ZodLiteral<"container">]>;
+            ref: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ExportIndex = z.infer<typeof exportIndexSchema>;
+export declare const parseExportIndex: (raw: unknown) => ExportIndex;
+export {};

package/dist/deployment/artifactsExportTypes.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+/**
+ * `spawnfile.export-index.v1` — the machine contract `spawnfile artifacts
+ * export` writes at `<out>/spawnfile/export-index.json` (contracts.md's
+ * Spawnfile export-index registry row; Decision 21's Piece 3). It is the
+ * only artifact `simfile observe` needs from spawnfile beyond the raw files
+ * themselves: a manifest of what was exported, from where, and its content
+ * hash, so a future `simfile.run-manifest.v1` can fold `files` straight into
+ * its own `artifacts` array (same `{path, sha256}` shape — see
+ * `ecosystem/simfile/src/observe/manifest.ts`) without re-deriving anything.
+ *
+ * `sha256` is a bare 64-character lowercase hex digest (no `sha256:`
+ * prefix), matching `simfile.run-manifest.v1`'s `artifacts[].sha256` exactly
+ * — this is deliberate so folding this index into that manifest is a
+ * straight copy, never a reformat.
+ */
+export const EXPORT_INDEX_VERSION = "spawnfile.export-index.v1";
+const sha256HexSchema = z
+    .string()
+    .regex(/^[0-9a-f]{64}$/u, "sha256 must be a 64-character lowercase hex digest");
+const exportSourceSchema = z
+    .object({
+    kind: z.union([z.literal("volume"), z.literal("container")]),
+    ref: z.string().min(1)
+})
+    .strict();
+const exportIndexFileSchema = z
+    .object({
+    path: z.string().min(1),
+    sha256: sha256HexSchema,
+    bytes: z.number().int().nonnegative(),
+    source: exportSourceSchema
+})
+    .strict();
+export const exportIndexSchema = z
+    .object({
+    version: z.literal(EXPORT_INDEX_VERSION),
+    run_id: z.string().min(1),
+    deployment: z.string().min(1),
+    exported_at: z.string().min(1),
+    files: z.array(exportIndexFileSchema)
+})
+    .strict();
+export const parseExportIndex = (raw) => {
+    const result = exportIndexSchema.safeParse(raw);
+    if (!result.success) {
+        throw new Error(`invalid ${EXPORT_INDEX_VERSION}: ${result.error.issues
+            .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+            .join("; ")}`);
+    }
+    return result.data;
+};

package/dist/deployment/buildImageCacheStore.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+export declare const BUILD_IMAGE_CACHE_VERSION: "spawnfile.build-image-cache.v1";
+export declare const buildImageCacheEntrySchema: z.ZodObject<{
+    compileFingerprint: z.ZodString;
+    contextDigest: z.ZodString;
+    dockerContext: z.ZodNullable<z.ZodString>;
+    imageId: z.ZodString;
+    imageTag: z.ZodString;
+    projectRoot: z.ZodString;
+    version: z.ZodLiteral<"spawnfile.build-image-cache.v1">;
+    writtenAt: z.ZodString;
+}, z.core.$strict>;
+export type BuildImageCacheEntry = z.infer<typeof buildImageCacheEntrySchema>;
+export interface BuildImageCacheKeyInput {
+    dockerContext?: string | null;
+    imageTag: string;
+    projectRoot: string;
+}
+export declare const createBuildImageCacheKey: (input: BuildImageCacheKeyInput) => string;
+export declare const resolveBuildImageCacheDirectory: () => string;
+export declare const resolveBuildImageCachePath: (input: BuildImageCacheKeyInput) => string;
+export declare const readBuildImageCacheEntry: (input: BuildImageCacheKeyInput) => Promise<BuildImageCacheEntry | null>;
+export declare const writeBuildImageCacheEntry: (entry: BuildImageCacheEntry) => Promise<boolean>;

package/dist/deployment/buildImageCacheStore.js

@@ -0,0 +1,54 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { resolveSpawnfileHome } from "../auth/index.js";
+import { ensureDirectory } from "../filesystem/index.js";
+export const BUILD_IMAGE_CACHE_VERSION = "spawnfile.build-image-cache.v1";
+export const buildImageCacheEntrySchema = z.object({
+    compileFingerprint: z.string().min(1),
+    contextDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+    dockerContext: z.string().min(1).nullable(),
+    imageId: z.string().min(1),
+    imageTag: z.string().min(1),
+    projectRoot: z.string().min(1),
+    version: z.literal(BUILD_IMAGE_CACHE_VERSION),
+    writtenAt: z.string().min(1)
+}).strict();
+export const createBuildImageCacheKey = (input) => createHash("sha256")
+    .update(`${input.projectRoot}\0${input.imageTag}\0${input.dockerContext ?? ""}`)
+    .digest("hex");
+export const resolveBuildImageCacheDirectory = () => path.join(resolveSpawnfileHome(), "build-image-cache");
+export const resolveBuildImageCachePath = (input) => path.join(resolveBuildImageCacheDirectory(), `${createBuildImageCacheKey(input)}.json`);
+export const readBuildImageCacheEntry = async (input) => {
+    try {
+        const source = await readFile(resolveBuildImageCachePath(input), "utf8");
+        return buildImageCacheEntrySchema.parse(JSON.parse(source));
+    }
+    catch {
+        return null;
+    }
+};
+export const writeBuildImageCacheEntry = async (entry) => {
+    let temporaryPath = null;
+    try {
+        const parsed = buildImageCacheEntrySchema.parse(entry);
+        const directory = resolveBuildImageCacheDirectory();
+        await ensureDirectory(directory);
+        const destinationPath = resolveBuildImageCachePath(parsed);
+        temporaryPath = path.join(directory, `.${path.basename(destinationPath)}.${process.pid}.${randomUUID()}.tmp`);
+        await writeFile(temporaryPath, `${JSON.stringify(parsed, null, 2)}\n`, {
+            encoding: "utf8",
+            mode: 0o600
+        });
+        await rename(temporaryPath, destinationPath);
+        temporaryPath = null;
+        return true;
+    }
+    catch {
+        if (temporaryPath) {
+            await rm(temporaryPath, { force: true }).catch(() => undefined);
+        }
+        return false;
+    }
+};

package/dist/deployment/deploymentLifecycleCorrelation.d.ts

@@ -0,0 +1,11 @@
+import type { DeploymentRecord } from "./record.js";
+export interface DeploymentLifecycleCorrelation {
+    compile_fingerprint: string;
+    deployment_instance_digest: string;
+    deployment: string;
+    run_id: string | null;
+    target: string;
+}
+export declare const createDeploymentInstanceDigest: (record: DeploymentRecord) => string;
+export declare const createDeploymentLifecycleCorrelation: (record: DeploymentRecord) => DeploymentLifecycleCorrelation;
+export declare const assertDeploymentLifecycleCorrelation: (record: DeploymentRecord, expected: DeploymentLifecycleCorrelation | undefined) => void;

package/dist/deployment/deploymentLifecycleCorrelation.js

@@ -0,0 +1,33 @@
+import { createHash } from "node:crypto";
+import { SpawnfileError } from "../shared/index.js";
+const canonical = (value) => {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonical(record[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+};
+export const createDeploymentInstanceDigest = (record) => {
+    const { export_index: _mutableExport, ...immutable } = record;
+    return `sha256:${createHash("sha256")
+        .update(canonical(immutable))
+        .digest("hex")}`;
+};
+export const createDeploymentLifecycleCorrelation = (record) => ({
+    compile_fingerprint: record.compile_fingerprint,
+    deployment: record.name,
+    deployment_instance_digest: createDeploymentInstanceDigest(record),
+    run_id: record.run_id ?? null,
+    target: JSON.stringify(record.target),
+});
+export const assertDeploymentLifecycleCorrelation = (record, expected) => {
+    if (expected &&
+        JSON.stringify(createDeploymentLifecycleCorrelation(record)) !==
+            JSON.stringify(expected))
+        throw new SpawnfileError("runtime_error", "Deployment changed after lifecycle admission; refusing effect");
+};

package/dist/deployment/dockerInspect.d.ts

@@ -11,6 +11,7 @@ export interface DockerUnitInspection {
     exists: boolean | null;
     exitCode: number | null;
     finishedAt: string | null;
+    identity: DockerDeploymentIdentity | null;
     imageId: string | null;
     message: string;
     restartCount: number | null;
@@ -20,6 +21,14 @@ export interface DockerUnitInspection {
     status: string | null;
     unitId: string;
 }
+export interface DockerDeploymentIdentity {
+    readonly compileFingerprint: string;
+    readonly deployment: string;
+    readonly project: string;
+    readonly runId: string;
+    readonly unit: string;
+    readonly version: string;
+}
 export type DockerInspectionResult = Map<string, DockerUnitInspection>;
 export interface DockerInspectOptions {
     dockerCommand?: string;

package/dist/deployment/dockerInspect.js

@@ -1,10 +1,30 @@
 import { execFile as execFileCallback } from "node:child_process";
 import { promisify } from "node:util";
+import { dockerDeploymentLabelKeys } from "./dockerLabels.js";
 import { dockerContextNameForTarget, verifyDockerDeploymentTarget } from "./target.js";
 const execFile = promisify(execFileCallback);
 const toStringOrNull = (value) => typeof value === "string" && value.length > 0 ? value : null;
 const toNumberOrNull = (value) => typeof value === "number" && Number.isFinite(value) ? value : null;
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const identifierLabelValuePattern = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/;
+const identityFromInspection = (inspected) => {
+    const config = isRecord(inspected.Config) ? inspected.Config : null;
+    const labels = config && isRecord(config.Labels) ? config.Labels : null;
+    if (!labels)
+        return null;
+    const values = {
+        compileFingerprint: labels[dockerDeploymentLabelKeys.compileFingerprint],
+        deployment: labels[dockerDeploymentLabelKeys.deployment],
+        project: labels[dockerDeploymentLabelKeys.project],
+        runId: labels[dockerDeploymentLabelKeys.runId],
+        unit: labels[dockerDeploymentLabelKeys.unit],
+        version: labels[dockerDeploymentLabelKeys.version]
+    };
+    if (Object.values(values).some((value) => typeof value !== "string" || !identifierLabelValuePattern.test(value))) {
+        return null;
+    }
+    return values;
+};
 const targetRefForUnit = (unit) => unit.container_id ?? unit.container_name;
 const argsForInspect = (record, targetRef) => {
     const context = dockerContextNameForTarget(record.target);
@@ -46,9 +66,10 @@ const inspectionFromState = (unitId, unit, inspected, state) => {
         exists: true,
         exitCode: toNumberOrNull(state.ExitCode),
         finishedAt: toStringOrNull(state.FinishedAt),
+        identity: running === true ? identityFromInspection(inspected) : null,
         imageId,
         message: drift.length > 0 ? `${baseMessage}; ${drift.join("; ")}` : baseMessage,
-        restartCount: toNumberOrNull(state.RestartCount),
+        restartCount: toNumberOrNull(inspected.RestartCount),
         running,
         severity: drift.length > 0 ? "warn" : running === false ? "error" : "ok",
         startedAt: toStringOrNull(state.StartedAt),
@@ -62,6 +83,7 @@ const missingInspection = (unitId, message) => ({
     exists: false,
     exitCode: null,
     finishedAt: null,
+    identity: null,
     imageId: null,
     message,
     restartCount: null,
@@ -77,6 +99,7 @@ const unknownInspection = (unitId, message, severity = "unknown") => ({
     exists: null,
     exitCode: null,
     finishedAt: null,
+    identity: null,
     imageId: null,
     message,
     restartCount: null,

package/dist/deployment/dockerLabels.d.ts

@@ -2,6 +2,7 @@ export declare const dockerDeploymentLabelKeys: {
     readonly compileFingerprint: "com.spawnfile.compile_fingerprint";
     readonly deployment: "com.spawnfile.deployment";
     readonly project: "com.spawnfile.project";
+    readonly runId: "com.spawnfile.run_id";
     readonly unit: "com.spawnfile.unit";
     readonly version: "com.spawnfile.version";
 };
@@ -9,6 +10,7 @@ export interface DockerDeploymentLabelInput {
     compileFingerprint: string;
     deployment: string;
     project: string;
+    runId?: string;
     unit: string;
     version: string;
 }

package/dist/deployment/dockerLabels.js

@@ -3,6 +3,7 @@ export const dockerDeploymentLabelKeys = {
     compileFingerprint: "com.spawnfile.compile_fingerprint",
     deployment: "com.spawnfile.deployment",
     project: "com.spawnfile.project",
+    runId: "com.spawnfile.run_id",
     unit: "com.spawnfile.unit",
     version: "com.spawnfile.version"
 };
@@ -17,6 +18,7 @@ export const createDockerDeploymentLabels = (input) => {
         [dockerDeploymentLabelKeys.compileFingerprint]: input.compileFingerprint,
         [dockerDeploymentLabelKeys.deployment]: input.deployment,
         [dockerDeploymentLabelKeys.project]: input.project,
+        ...(input.runId ? { [dockerDeploymentLabelKeys.runId]: input.runId } : {}),
         [dockerDeploymentLabelKeys.unit]: input.unit,
         [dockerDeploymentLabelKeys.version]: input.version
     };