spawnfile 0.1.13 → 0.1.17

package/dist/deployment/artifactsExportPlan.js

@@ -0,0 +1,185 @@
+import path from "node:path/posix";
+import { DAIMON_GROK_TURN_USAGE_LEDGER } from "../runtime/daimon/contractManifest.js";
+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`
+            }
+        }];
+}));
+/** The persistent-mount id the Daimon adapter gives the per-turn engine usage ledger
+ * (`src/runtime/daimon/config.ts`). Deliberately still says `grok` now that AGY writes
+ * there too: the id is the volume's identity, and renaming it orphans every existing
+ * deployment's accumulated ledger. */
+const DAIMON_USAGE_MOUNT_ID = "daimon-grok-usage-ledger";
+/** Daimon usage: the organization-wide per-turn engine token ledger.
+ *
+ * Unlike the causal streams above this is NOT per agent -- one exclusive-reattach volume
+ * carries every metered turn for the whole Daimon host -- so it exports flat under
+ * `raw/daimon/`, the way a single managed Moltnet network exports flat under
+ * `raw/moltnet/`. Flat also keeps it clear of the `raw/daimon/<slug>/` directories the
+ * per-agent causal files use.
+ *
+ * BOTH generations ship. The broker rotates by size at
+ * `DAIMON_GROK_TURN_USAGE_LEDGER.rotateBytes`, so a long-lived deployment's earlier turns
+ * live in `usage.jsonl.1`; exporting only the live file would silently truncate history
+ * for exactly the runs expensive enough to care about. This is the same rotation the read
+ * path already handles (`src/runtime/usageLedgerRead.ts` reads both generations).
+ *
+ * The mount root IS the ledger directory (`mountPath` is
+ * `DAIMON_GROK_TURN_USAGE_LEDGER.directoryPath`), so both names are resolved as
+ * mount-relative paths off the pinned contract constants rather than written out here --
+ * if the contract ever moves the ledger, this follows it instead of silently exporting
+ * nothing.
+ *
+ * Optional, because absent must stay distinguishable from empty: a codex-only
+ * organization is never provisioned this volume and writes no ledger at all, which is
+ * legitimate, and the mount is absent from the report entirely in that case. Where the
+ * volume exists but a generation does not (no rotation yet, or no metered turn yet), the
+ * executor records it under `missingOptionalFiles` rather than as an exported empty file
+ * (`artifactsExport.ts`). */
+const planDaimonUsageFiles = (mounts) => {
+    const mount = mounts.get(DAIMON_USAGE_MOUNT_ID);
+    if (!mount) {
+        return [];
+    }
+    return [
+        DAIMON_GROK_TURN_USAGE_LEDGER.filePath,
+        DAIMON_GROK_TURN_USAGE_LEDGER.rotatedFilePath
+    ].map((absolutePath) => {
+        const volumePath = path.relative(DAIMON_GROK_TURN_USAGE_LEDGER.directoryPath, absolutePath);
+        return {
+            optional: true,
+            relativePath: `raw/daimon/${volumePath}`,
+            source: { kind: "volume", volumeName: mount.volume_name, volumePath }
+        };
+    });
+};
+/** 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),
+        ...planDaimonUsageFiles(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/canaryCutover.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+export declare const deploymentIdentitySchema: z.ZodObject<{
+    version: z.ZodLiteral<"spawnfile.deployment-identity.v1">;
+    run_id: z.ZodString;
+    fingerprint: z.ZodString;
+    deployment_name: z.ZodString;
+    deployment_mode: z.ZodEnum<{
+        project: "project";
+        image: "image";
+    }>;
+    image_id: z.ZodString;
+    organization_unit_id: z.ZodString;
+    organization_compile_fingerprint: z.ZodString;
+    organization_world_binding_digest: z.ZodNullable<z.ZodString>;
+    topology_sha256: z.ZodString;
+}, z.core.$strict>;
+type Execute = (command: string, args: string[]) => Promise<string | void>;
+type Inspect = (command: string, args: string[]) => Promise<string>;
+export declare const verifyCandidatePortIsolation: (liveReport: unknown, candidateReport: unknown) => number[];
+export declare const issueDeploymentIdentity: (readinessPath: string, deploymentMode: "project" | "image", dockerCommand: string, imageInspect?: Inspect) => Promise<Record<string, unknown>>;
+export declare const runCanaryCutover: (input: {
+    liveReportPath: string;
+    candidateReportPath: string;
+    readinessPath: string;
+    expectedIdentity: unknown;
+    dockerCommand: string;
+    nonce: string;
+    transactionPath: string;
+    ingressCommand: string;
+    ingressArgs: string[];
+    ingressReceiptPath: string;
+    teardownCommand: string;
+    teardownArgs: string[];
+    teardownPolicy: "export" | "force";
+    teardownProjectPath: string;
+    teardownCompiledPath: string;
+    decisionReceiptPath: string;
+    fromDeployment: string;
+    toDeployment: string;
+}, runner?: Execute, imageInspect?: Inspect) => Promise<Record<string, unknown>>;
+export declare const verifyEquivalentRollbackReadiness: (rollbackReadinessPath: string, expectedIdentity: unknown) => Promise<void>;
+export {};

package/dist/deployment/canaryCutover.js

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+import { execFile as execFileCallback } from "node:child_process";
+import { link, open, readFile, rm } from "node:fs/promises";
+import { promisify } from "node:util";
+import path from "node:path";
+import { z } from "zod";
+import { SpawnfileError } from "../shared/index.js";
+import { parseUpReceipt } from "./upReceiptTypes.js";
+import { parseDownReceipt } from "./downReceiptTypes.js";
+const execFile = promisify(execFileCallback);
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/u), runId = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/u), nonce = z.string().regex(/^[a-f0-9]{32}$/u);
+const ingressReceiptSchema = z.object({ version: z.literal("spawnfile.ingress-cutover-receipt.v1"), state: z.literal("switched"), nonce, from_deployment: z.string().min(1), to_deployment: z.string().min(1), target_run_id: runId, readiness_sha256: digest }).strict();
+const decisionReceiptSchema = z.object({ version: z.literal("spawnfile.canary-decision-receipt.v1"), decision: z.literal("cutover"), nonce, target_run_id: runId, deployment_mode: z.enum(["project", "image"]), target_identity_sha256: digest, ingress_receipt_sha256: digest, teardown_checkpoint_sha256: digest, down_receipt_sha256: digest }).strict();
+const reportSchema = z.object({
+    persistent_mounts: z.array(z.object({
+        id: z.string().min(1),
+        lifecycle: z.literal("exclusive-reattach").optional()
+    }).passthrough()).max(4096).optional().default([]),
+    published_ports: z.array(z.number().int().min(1).max(65535)).max(64)
+}).passthrough();
+export const deploymentIdentitySchema = z.object({ version: z.literal("spawnfile.deployment-identity.v1"), run_id: runId, fingerprint: z.string().min(1), deployment_name: z.string().min(1), deployment_mode: z.enum(["project", "image"]), image_id: z.string().regex(/^sha256:[a-f0-9]{64}$/u), organization_unit_id: z.string().min(1), organization_compile_fingerprint: z.string().min(1), organization_world_binding_digest: digest.nullable(), topology_sha256: digest }).strict();
+const execute = async (command, args) => (await execFile(command, args, { encoding: "utf8", timeout: 30_000, maxBuffer: 1_048_576 })).stdout;
+const inspect = async (command, args) => (await execFile(command, args, { encoding: "utf8", timeout: 10_000, maxBuffer: 1_048_576 })).stdout;
+const sha = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+const canonical = (value) => JSON.stringify(value, (_key, item) => item && typeof item === "object" && !Array.isArray(item) ? Object.fromEntries(Object.entries(item).sort(([left], [right]) => left.localeCompare(right))) : item);
+const topologyDigest = (receipt) => sha(canonical({ compiled_schedule: receipt.compiled_schedule, engines: receipt.engines ?? [], moltnet_release: receipt.moltnet_release ?? null }));
+export const verifyCandidatePortIsolation = (liveReport, candidateReport) => {
+    const liveReportValue = reportSchema.parse(liveReport), candidateReportValue = reportSchema.parse(candidateReport);
+    const live = new Set(liveReportValue.published_ports), candidate = candidateReportValue.published_ports;
+    if (candidate.some((port) => live.has(port)) || new Set(candidate).size !== candidate.length)
+        throw new SpawnfileError("validation_error", "Candidate published ports are not mechanically isolated from live");
+    const liveMounts = new Map(liveReportValue.persistent_mounts.map((mount) => [mount.id, mount]));
+    const sharedExclusive = candidateReportValue.persistent_mounts.find((mount) => liveMounts.has(mount.id)
+        && (mount.lifecycle === "exclusive-reattach" || liveMounts.get(mount.id)?.lifecycle === "exclusive-reattach"));
+    if (sharedExclusive)
+        throw new SpawnfileError("validation_error", `Candidate shares exclusive persistent mount ${sharedExclusive.id}; use stop-and-reattach deployment instead of concurrent canary`);
+    return candidate;
+};
+const verifyIdentity = (receipt, expected) => {
+    const ready = receipt.organization_ready;
+    if (receipt.run_id !== expected.run_id || receipt.fingerprint !== expected.fingerprint || receipt.deployment.name !== expected.deployment_name || ready?.state !== "ready" || ready.unit_id !== expected.organization_unit_id || ready.compile_fingerprint !== expected.organization_compile_fingerprint || ready.world_binding_digest !== expected.organization_world_binding_digest || topologyDigest(receipt) !== expected.topology_sha256)
+        throw new SpawnfileError("validation_error", "Readiness does not bind the exact intended deployment identity and topology");
+};
+export const issueDeploymentIdentity = async (readinessPath, deploymentMode, dockerCommand, imageInspect = inspect) => {
+    const receipt = parseUpReceipt(JSON.parse(await readFile(readinessPath, "utf8"))), ready = receipt.organization_ready;
+    if (receipt.run_id === null || receipt.deployment.name === null || receipt.deployment.container_ids.length < 1 || ready?.state !== "ready")
+        throw new SpawnfileError("validation_error", "Deployment is not identity-ready");
+    const images = await Promise.all(receipt.deployment.container_ids.map(async (container) => (await imageInspect(dockerCommand, ["inspect", "--format", "{{.Image}}", container])).trim()));
+    if (!images[0] || images.some((image) => image !== images[0]))
+        throw new SpawnfileError("validation_error", "Deployment containers do not share one exact image identity");
+    return deploymentIdentitySchema.parse({ version: "spawnfile.deployment-identity.v1", run_id: receipt.run_id, fingerprint: receipt.fingerprint, deployment_name: receipt.deployment.name, deployment_mode: deploymentMode, image_id: images[0], organization_unit_id: ready.unit_id, organization_compile_fingerprint: ready.compile_fingerprint, organization_world_binding_digest: ready.world_binding_digest, topology_sha256: topologyDigest(receipt) });
+};
+const syncParent = async (filePath) => { const directory = await open(path.dirname(filePath), "r"); try {
+    await directory.sync();
+}
+finally {
+    await directory.close();
+} };
+const publishExclusive = async (filePath, value) => { const temporary = `${filePath}.tmp-${process.pid}`; const file = await open(temporary, "wx", 0o600); try {
+    await file.writeFile(`${JSON.stringify(value)}\n`);
+    await file.sync();
+}
+finally {
+    await file.close();
+} try {
+    await link(temporary, filePath);
+    await syncParent(filePath);
+}
+finally {
+    await rm(temporary, { force: true });
+    await syncParent(filePath);
+} };
+const exists = async (filePath) => await readFile(filePath).then(() => true, (error) => error.code === "ENOENT" ? false : Promise.reject(error));
+export const runCanaryCutover = async (input, runner = execute, imageInspect = inspect) => {
+    const expected = deploymentIdentitySchema.parse(input.expectedIdentity), operationNonce = nonce.parse(input.nonce);
+    if (input.ingressArgs.length > 32 || input.teardownArgs.length > 32 || [...input.ingressArgs, ...input.teardownArgs].some((arg) => arg.length > 4096))
+        throw new SpawnfileError("validation_error", "Canary command arguments exceed bounds");
+    const lifecycleId = `lci_canary_${operationNonce}`, exportIndex = input.teardownArgs.indexOf("--export-to"), prefix = ["down", input.teardownProjectPath, "--compiled", input.teardownCompiledPath, "--deployment", input.fromDeployment], expectedTeardownArgs = input.teardownPolicy === "export" ? [...prefix, "--export-to", input.teardownArgs[exportIndex + 1] ?? "", "--json", "--lifecycle-invocation", lifecycleId] : [...prefix, "--force", "--json", "--lifecycle-invocation", lifecycleId];
+    const canonicalPath = (value) => path.isAbsolute(value) && path.resolve(value) === value && path.normalize(value) === value;
+    if (!canonicalPath(input.teardownProjectPath) || !canonicalPath(input.teardownCompiledPath) || path.basename(input.teardownCommand) !== "spawnfile" || (input.teardownPolicy === "export" && (exportIndex < 0 || !expectedTeardownArgs[7])) || canonical(input.teardownArgs) !== canonical(expectedTeardownArgs))
+        throw new SpawnfileError("validation_error", "Teardown is not the exact canonical Spawnfile lifecycle down operation");
+    verifyCandidatePortIsolation(JSON.parse(await readFile(input.liveReportPath, "utf8")), JSON.parse(await readFile(input.candidateReportPath, "utf8")));
+    const readinessBytes = await readFile(input.readinessPath), readiness = parseUpReceipt(JSON.parse(readinessBytes.toString("utf8")));
+    verifyIdentity(readiness, expected);
+    if (readiness.deployment.container_ids.length < 1)
+        throw new SpawnfileError("validation_error", "Ready deployment has no image-bearing containers");
+    for (const container of readiness.deployment.container_ids)
+        if ((await imageInspect(input.dockerCommand, ["inspect", "--format", "{{.Image}}", container])).trim() !== expected.image_id)
+            throw new SpawnfileError("validation_error", "Ready deployment image does not match intended identity");
+    const binding = sha(canonical({ ...input, expectedIdentity: expected }));
+    const transaction = { version: "spawnfile.canary-transaction.v1", state: "reserved", nonce: operationNonce, binding_sha256: binding };
+    const recovering = await exists(input.transactionPath);
+    if (recovering) {
+        const prior = JSON.parse(await readFile(input.transactionPath, "utf8"));
+        if (prior.version !== transaction.version || prior.nonce !== operationNonce || prior.binding_sha256 !== binding)
+            throw new SpawnfileError("validation_error", "Canary transaction authority does not match");
+    }
+    else {
+        if (await exists(input.ingressReceiptPath) || await exists(input.decisionReceiptPath))
+            throw new SpawnfileError("validation_error", "Stale canary receipt exists before transaction reservation");
+        await publishExclusive(input.transactionPath, transaction);
+    }
+    if (!await exists(input.ingressReceiptPath))
+        await runner(input.ingressCommand, input.ingressArgs);
+    const ingressBytes = await readFile(input.ingressReceiptPath), ingress = ingressReceiptSchema.parse(JSON.parse(ingressBytes.toString("utf8")));
+    if (ingress.nonce !== operationNonce || ingress.from_deployment !== input.fromDeployment || ingress.to_deployment !== input.toDeployment || ingress.target_run_id !== expected.run_id || ingress.readiness_sha256 !== sha(readinessBytes))
+        throw new SpawnfileError("validation_error", "Ingress receipt does not bind the exact ready target and transaction nonce");
+    const teardownStartedPath = `${input.transactionPath}.teardown-started`, teardownReceiptPath = `${input.transactionPath}.teardown-receipt`, teardownCheckpointPath = `${input.transactionPath}.teardown-complete`, checkpointBase = { nonce: operationNonce, binding_sha256: binding, ingress_receipt_sha256: sha(ingressBytes), lifecycle_invocation: lifecycleId };
+    if (!await exists(teardownCheckpointPath)) {
+        if (await exists(input.decisionReceiptPath))
+            throw new SpawnfileError("validation_error", "Canary decision exists without its teardown checkpoint");
+        if (!await exists(teardownStartedPath))
+            await publishExclusive(teardownStartedPath, { version: "spawnfile.canary-teardown-started.v1", ...checkpointBase });
+        if (!await exists(teardownReceiptPath)) {
+            const output = await runner(input.teardownCommand, input.teardownArgs), down = parseDownReceipt(JSON.parse(typeof output === "string" ? output : ""));
+            if (down.deployment !== input.fromDeployment || down.errors.length !== 0)
+                throw new SpawnfileError("validation_error", "Down receipt does not prove exact teardown completion");
+            await publishExclusive(teardownReceiptPath, down);
+        }
+        const downBytes = await readFile(teardownReceiptPath), down = parseDownReceipt(JSON.parse(downBytes.toString("utf8")));
+        if (down.deployment !== input.fromDeployment || down.errors.length !== 0)
+            throw new SpawnfileError("validation_error", "Stored down receipt does not bind the teardown operation");
+        await publishExclusive(teardownCheckpointPath, { version: "spawnfile.canary-teardown-checkpoint.v1", ...checkpointBase, down_receipt_sha256: sha(downBytes) });
+    }
+    else {
+        const downBytes = await readFile(teardownReceiptPath), down = parseDownReceipt(JSON.parse(downBytes.toString("utf8"))), expectedCheckpoint = { version: "spawnfile.canary-teardown-checkpoint.v1", ...checkpointBase, down_receipt_sha256: sha(downBytes) };
+        if (down.deployment !== input.fromDeployment || down.errors.length !== 0 || canonical(JSON.parse(await readFile(teardownCheckpointPath, "utf8"))) !== canonical(expectedCheckpoint))
+            throw new SpawnfileError("validation_error", "Canary teardown checkpoint does not match the recovered transaction");
+    }
+    const checkpointBytes = await readFile(teardownCheckpointPath), downBytes = await readFile(teardownReceiptPath), decision = { version: "spawnfile.canary-decision-receipt.v1", decision: "cutover", nonce: operationNonce, target_run_id: expected.run_id, deployment_mode: expected.deployment_mode, target_identity_sha256: sha(canonical(expected)), ingress_receipt_sha256: sha(ingressBytes), teardown_checkpoint_sha256: sha(checkpointBytes), down_receipt_sha256: sha(downBytes) };
+    if (!await exists(input.decisionReceiptPath)) {
+        await publishExclusive(input.decisionReceiptPath, decision);
+        return decision;
+    }
+    const priorDecision = decisionReceiptSchema.parse(JSON.parse(await readFile(input.decisionReceiptPath, "utf8")));
+    if (canonical(priorDecision) !== canonical(decision))
+        throw new SpawnfileError("validation_error", "Canary decision receipt does not match the recovered transaction");
+    return priorDecision;
+};
+export const verifyEquivalentRollbackReadiness = async (rollbackReadinessPath, expectedIdentity) => { const expected = deploymentIdentitySchema.parse(expectedIdentity), rollback = parseUpReceipt(JSON.parse(await readFile(rollbackReadinessPath, "utf8"))); verifyIdentity(rollback, expected); };

package/dist/deployment/candidateDiagnostics.d.ts

@@ -0,0 +1,15 @@
+import type { DockerCommandRunner } from "../distribution/dockerRunner.js";
+export interface CandidateDiagnosticsInput {
+    candidateId: string;
+    deploymentName: string;
+    runDocker: DockerCommandRunner;
+    secretValues: string[];
+}
+export interface CandidateDiagnosticsResult {
+    path: string | null;
+    summary: string;
+}
+/** Redaction is best effort; diagnostic artifacts remain private operator data. */
+export declare const sanitizeCandidateDiagnostic: (text: string, secrets: string[]) => string;
+/** Collect before rollback deletes the only container-local startup evidence. */
+export declare const captureCandidateDiagnostics: (input: CandidateDiagnosticsInput) => Promise<CandidateDiagnosticsResult>;