spawnfile 0.1.14 → 0.1.17

package/dist/compiler/upReceipt.js

@@ -29,6 +29,54 @@ export const resolveCompiledEngines = (report) => (report.container?.runtime_ins
     .flatMap((instance) => Object.entries(instance.engine_by_node_id ?? {}))
     .map(([agent, engine]) => ({ agent, engine }))
     .sort((left, right) => left.agent.localeCompare(right.agent));
+const createReceiptMoltnetIdentity = (release) => {
+    if (!release)
+        return undefined;
+    // Discriminate on PROVENANCE, never on capability count. A published release
+    // now advertises `daimon-bridge` too (moltnet v0.1.18), so `length === 1` would
+    // route it into the local-development branch and reject it for lacking a
+    // `development` marker it is never supposed to have.
+    //
+    // The canonical list lives in `moltnetReleaseAuthority.ts`, but the H2 boundary
+    // (`../deployment/organizationHandoffTypes.test.ts`) forbids this file from
+    // importing any `moltnet*` module, so the ordering is compared inline here the
+    // same way the local branch below already compares it. `upReceiptTypes.ts`'s
+    // schema is the authority that rejects any other list on parse.
+    const joined = release.capabilities.join("\0");
+    const receiptCapabilities = joined === "daimon-bridge\0pi-bridge"
+        ? ["daimon-bridge", "pi-bridge"]
+        : joined === "pi-bridge" ? ["pi-bridge"] : null;
+    if (receiptCapabilities === null) {
+        throw new SpawnfileError("runtime_error", "Moltnet receipt advertises unknown bridge capabilities");
+    }
+    if (!release.development) {
+        if (!release.release_version || !release.source_revision) {
+            throw new SpawnfileError("runtime_error", "Published Moltnet receipt lacks its pinned source identity");
+        }
+        return {
+            architecture: release.architecture,
+            asset: release.asset,
+            asset_sha256: release.asset_sha256,
+            capabilities: receiptCapabilities,
+            release_version: release.release_version,
+            source_revision: release.source_revision,
+            version: release.version
+        };
+    }
+    if (release.capabilities.join("\0") !== "daimon-bridge\0pi-bridge" ||
+        !release.source_sha256) {
+        throw new SpawnfileError("runtime_error", "Local Moltnet receipt lacks its development provenance");
+    }
+    return {
+        architecture: release.architecture,
+        asset: release.asset,
+        asset_sha256: release.asset_sha256,
+        capabilities: ["daimon-bridge", "pi-bridge"],
+        development: release.development,
+        source_sha256: release.source_sha256,
+        version: release.version
+    };
+};
 /**
  * Builds `spawnfile.up-receipt.v1` from a project-path `upProject()` result. Reads back
  * the deployment record `upProject` already wrote (for `run_id`/deployment name/container
@@ -70,10 +118,7 @@ export const buildUpReceipt = async (inputPath, result) => {
         compiled_schedule: compiledSchedule,
         engines: compiledEngines,
         ...(result.report.container?.moltnet?.release
-            ? { moltnet_release: {
-                    ...result.report.container.moltnet.release,
-                    capabilities: ["pi-bridge"]
-                } }
+            ? { moltnet_release: createReceiptMoltnetIdentity(result.report.container.moltnet.release) }
             : {}),
         ...(record?.organization_handoff ? { organization_handoff: record.organization_handoff } : {}),
         ...(record?.organization_handoff_handle ? { organization_handoff_handle: record.organization_handoff_handle } : {}),

package/dist/compiler/updateProjectModels.js

@@ -9,6 +9,7 @@ const AUTH_METHOD_PROVIDER_HINTS = {
     "api_key": "use a model provider like openai or anthropic, then pass --auth api_key",
     "claude-code": "use provider anthropic, then pass --auth claude-code",
     codex: "use provider openai, then pass --auth codex",
+    grok: "use provider xai with a Daimon grok engine agent, then pass --auth grok and declare reasoning_effort",
     none: "use a model provider like local, then pass --auth none"
 };
 const resolveTargetManifestPath = (inputPath) => getManifestPath(path.resolve(inputPath ?? process.cwd()));

package/dist/compiler/view/types.d.ts

@@ -10,7 +10,7 @@ export interface OrganizationViewSkillSummary {
 }
 export interface OrganizationViewResourceSummary {
     id: string;
-    kind: "git" | "volume";
+    kind: "bundle" | "git" | "volume";
     mode: "mutable" | "readonly";
     mount: string;
     sharing: "per_agent" | "team";

package/dist/compiler/workspaceBundleArtifacts.d.ts

@@ -0,0 +1,3 @@
+import type { CompilePlan } from "./types.js";
+export declare const validateWorkspaceBundleTar: (bytes: Buffer) => void;
+export declare const stageWorkspaceBundles: (outputDirectory: string, plan: CompilePlan) => Promise<boolean>;

package/dist/compiler/workspaceBundleArtifacts.js

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+import { copyFile, mkdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { SpawnfileError } from "../shared/index.js";
+// Sanity bound for an operator-declared local tar; integrity comes from its digest, not its size.
+const CAP = 536_870_912, BLOCK = 512;
+// Sanity bound on an operator-declared local tar; integrity comes from the declared digest.
+const MAX_WORKSPACE_BUNDLE_ENTRIES = 65_536;
+const fail = (message = "Workspace bundle contains an invalid or unsafe tar entry") => { throw new SpawnfileError("validation_error", message); };
+const textField = (field) => { const nul = field.indexOf(0); return field.subarray(0, nul < 0 ? field.length : nul).toString("utf8"); };
+const octal = (field, allowEmpty = false) => {
+    const value = field.toString("ascii").replace(/\0.*$/u, "").trim();
+    if (value === "" && allowEmpty)
+        return 0;
+    if (!/^[0-7]+$/u.test(value))
+        fail();
+    const parsed = Number.parseInt(value, 8);
+    if (!Number.isSafeInteger(parsed) || parsed < 0)
+        fail();
+    return parsed;
+};
+const validPath = (value, directory) => {
+    const name = directory && value.endsWith("/") ? value.slice(0, -1) : value;
+    if (!name || name.startsWith("/") || name.includes("\\") || name.includes("\0"))
+        fail();
+    const parts = name.split("/");
+    if (parts.some((part) => !part || part === "." || part === ".."))
+        fail();
+    return parts.join("/");
+};
+const validChecksum = (header) => {
+    const expected = octal(header.subarray(148, 156));
+    let actual = 0;
+    for (let index = 0; index < BLOCK; index += 1)
+        actual += index >= 148 && index < 156 ? 32 : header[index];
+    return actual === expected;
+};
+export const validateWorkspaceBundleTar = (bytes) => {
+    if (bytes.length < BLOCK * 2 || bytes.length % BLOCK !== 0)
+        fail("Workspace bundle is truncated or lacks exact ustar termination");
+    let offset = 0, entries = 0, terminated = false;
+    const names = new Set();
+    while (offset + BLOCK <= bytes.length) {
+        const header = bytes.subarray(offset, offset + BLOCK);
+        if (header.every((byte) => byte === 0)) {
+            if (offset + BLOCK * 2 > bytes.length || !bytes.subarray(offset, offset + BLOCK * 2).every((byte) => byte === 0) || !bytes.subarray(offset + BLOCK * 2).every((byte) => byte === 0))
+                fail("Workspace bundle has invalid termination or trailing bytes");
+            terminated = true;
+            break;
+        }
+        if (textField(header.subarray(257, 263)) !== "ustar" || !validChecksum(header))
+            fail();
+        for (const [start, end, empty] of [[100, 108, false], [108, 116, true], [116, 124, true], [124, 136, false], [136, 148, true], [329, 337, true], [337, 345, true]])
+            octal(header.subarray(start, end), empty);
+        const type = header[156] === 0 ? "0" : String.fromCharCode(header[156]);
+        if (type !== "0" && type !== "5")
+            fail();
+        const size = octal(header.subarray(124, 136));
+        if (type === "5" && size !== 0)
+            fail();
+        const prefix = textField(header.subarray(345, 500)), rawName = textField(header.subarray(0, 100));
+        const effective = validPath(prefix ? `${prefix}/${rawName}` : rawName, type === "5");
+        if (names.has(effective))
+            fail("Workspace bundle contains duplicate effective paths");
+        names.add(effective);
+        offset += BLOCK + Math.ceil(size / BLOCK) * BLOCK;
+        entries += 1;
+        if (offset > bytes.length)
+            fail("Workspace bundle is truncated or exceeds entry bounds");
+        if (entries > MAX_WORKSPACE_BUNDLE_ENTRIES)
+            fail("Workspace bundle exceeds the maximum entry count");
+    }
+    if (!terminated)
+        fail("Workspace bundle is truncated or lacks exact ustar termination");
+    if (entries === 0)
+        fail("Workspace bundle is empty");
+};
+export const stageWorkspaceBundles = async (outputDirectory, plan) => {
+    const bundles = new Map();
+    for (const node of plan.nodes)
+        if (node.kind === "agent")
+            for (const resource of node.value.workspaceResources ?? []) {
+                if (resource.kind !== "bundle")
+                    continue;
+                const source = path.resolve(path.dirname(resource.scope.key), resource.source), prior = bundles.get(resource.sha256);
+                if (prior && prior !== source)
+                    throw new SpawnfileError("validation_error", "Workspace bundle digest maps to multiple sources");
+                bundles.set(resource.sha256, source);
+            }
+    if (bundles.size === 0)
+        return false;
+    const destination = path.join(outputDirectory, "container/workspace-bundles");
+    await mkdir(destination, { recursive: true });
+    for (const [identity, source] of bundles) {
+        const info = await stat(source);
+        if (!info.isFile() || info.size < 1 || info.size > CAP)
+            throw new SpawnfileError("validation_error", "Workspace bundle must be a bounded regular tar file");
+        const bytes = await readFile(source);
+        const actual = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+        if (actual !== identity)
+            throw new SpawnfileError("validation_error", "Workspace bundle checksum mismatch");
+        validateWorkspaceBundleTar(bytes);
+        await copyFile(source, path.join(destination, `${identity.slice(7)}.tar`));
+    }
+    return true;
+};

package/dist/compiler/workspaceResources.d.ts

@@ -10,16 +10,19 @@ export type ResolvedWorkspaceResource = TeamWorkspaceResource & {
     sharing: WorkspaceResourceSharing;
 };
 export interface WorkspaceResourcePlan {
+    archivePath?: string;
     backingPath: string;
     branch?: string;
     id: string;
-    kind: "git" | "volume";
+    kind: "bundle" | "git" | "volume";
     linkPath: string;
     mode: "mutable" | "readonly";
     mount: string;
     name?: string;
     ref?: string;
     sharing: WorkspaceResourceSharing;
+    sha256?: string;
+    source?: string;
     tag?: string;
     url?: string;
 }

package/dist/compiler/workspaceResources.js

@@ -14,6 +14,8 @@ const normalizeMount = (value) => {
     return collapsed.length > 1 ? collapsed.replace(/\/+$/u, "") : "/";
 };
 const normalizeResourceIdentity = (resource) => {
+    if (resource.kind === "bundle")
+        return JSON.stringify({ kind: resource.kind, mode: resource.mode, mount: normalizeMount(resource.mount), sha256: resource.sha256, source: resource.source, sharing: resource.sharing });
     if (resource.kind === "git") {
         return JSON.stringify({
             branch: resource.branch?.trim() ?? "",
@@ -39,12 +41,9 @@ const mountsOverlap = (left, right) => left === right ||
     left.startsWith(`${right}/`) ||
     right.startsWith(`${left}/`);
 const resolveSharing = (resource) => resource.sharing ?? "per_agent";
-const toResolvedResource = (resource, scope) => ({
-    ...resource,
-    mount: normalizeMount(resource.mount),
-    scope,
-    sharing: resolveSharing(resource)
-});
+const toResolvedResource = (resource, scope) => resource.kind === "bundle"
+    ? { ...resource, mount: normalizeMount(resource.mount), scope, sharing: "per_agent" }
+    : { ...resource, mount: normalizeMount(resource.mount), scope, sharing: resolveSharing(resource) };
 const createPathSegment = (value) => {
     const slug = slugify(value);
     const hash = createShortHash(value);
@@ -103,7 +102,13 @@ export const toWorkspaceResourcePlan = (resource, context) => resource.kind ===
         ...(resource.tag ? { tag: resource.tag } : {}),
         url: resource.url
     }
-    : {
+    : resource.kind === "bundle" ? {
+        archivePath: `/opt/spawnfile/workspace-bundles/${resource.sha256.slice(7)}.tar`,
+        backingPath: resolveBackingPath(resource, context.targetId), id: resource.id, kind: "bundle",
+        linkPath: resolveLinkPath(normalizeMount(resource.mount), context.workspacePath), mode: resource.mode,
+        mount: normalizeMount(resource.mount), sharing: resource.sharing, sha256: resource.sha256,
+        source: path.resolve(path.dirname(resource.scope.key), resource.source)
+    } : {
         backingPath: resolveBackingPath(resource, context.targetId),
         id: resource.id,
         kind: "volume",

package/dist/deployment/artifactsExportPlan.js

@@ -1,4 +1,5 @@
 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
@@ -122,6 +123,54 @@ const planDaimonFiles = (report, mounts) => (report.container?.runtime_instances
             }
         }];
 }));
+/** 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. */
@@ -130,6 +179,7 @@ export const planArtifactExports = (report) => {
     return [
         ...planMoltnetFiles(report, mounts),
         ...planMnemeFiles(report, mounts),
-        ...planDaimonFiles(report, mounts)
+        ...planDaimonFiles(report, mounts),
+        ...planDaimonUsageFiles(mounts)
     ];
 };

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>;

package/dist/deployment/candidateDiagnostics.js

@@ -0,0 +1,90 @@
+import { randomUUID } from "node:crypto";
+import { lstat, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveSpawnfileHome } from "../auth/index.js";
+import { redactDockerLogText } from "./dockerLogs.js";
+import { resolveHomeDeploymentDirectory } from "./homeStore.js";
+const outputLimit = 64 * 1024;
+const commandOptions = { captureStderr: true, maxOutputBytes: outputLimit, timeoutMs: 5_000 };
+const containerIdPattern = /^[a-f0-9]{64}$/u;
+/** Redaction is best effort; diagnostic artifacts remain private operator data. */
+export const sanitizeCandidateDiagnostic = (text, secrets) => redactDockerLogText(text, secrets)
+    .replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?(?:-----END [^-]*PRIVATE KEY-----|$)/gu, "[REDACTED PRIVATE KEY]")
+    .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gu, "[REDACTED JWT]")
+    .replace(/https?:\/\/[^\s<>"']+/giu, "[REDACTED URL]")
+    .replace(/\b([a-z0-9_-]*(?:authorization|cookie|password|secret|token|api[_-]?key)[a-z0-9_-]*)["']?\s*[:=]\s*[^\r\n]+/giu, "$1: [REDACTED]");
+const collect = async (runDocker, args) => {
+    try {
+        const bytes = await runDocker(args, commandOptions);
+        // Injectable runners must obey the same limit as the default Docker runner.
+        if (bytes.length > outputLimit)
+            throw new Error("limit");
+        return { available: true, text: bytes.toString("utf8") };
+    }
+    catch {
+        // Docker transport errors can contain command/env details; never persist them.
+        return { available: false, text: "Diagnostic command failed, timed out, or exceeded its byte limit" };
+    }
+};
+const summarizeState = (raw, secrets) => {
+    try {
+        const state = JSON.parse(raw);
+        const health = state.Health?.Status;
+        const status = ["created", "running", "paused", "restarting", "removing", "exited", "dead"].includes(String(state.Status))
+            ? state.Status : "unknown";
+        const parts = [`state=${status}`];
+        if (["starting", "healthy", "unhealthy"].includes(String(health)))
+            parts.push(`health=${health}`);
+        if (Number.isSafeInteger(state.ExitCode))
+            parts.push(`exit=${state.ExitCode}`);
+        if (state.OOMKilled === true)
+            parts.push("oom-killed");
+        const healthState = state.Health;
+        const text = (value) => typeof value === "string"
+            ? sanitizeCandidateDiagnostic(value, secrets).slice(0, 4_096) : "";
+        return { available: true, summary: parts.join(", "), error: text(state.Error),
+            healthOutput: Array.isArray(healthState?.Log) ? healthState.Log.slice(-3).map((entry) => text(entry && typeof entry === "object" ? entry.Output : null)) : [] };
+    }
+    catch {
+        return { available: false, summary: "state unavailable", error: "", healthOutput: [] };
+    }
+};
+/** Collect before rollback deletes the only container-local startup evidence. */
+export const captureCandidateDiagnostics = async (input) => {
+    if (!containerIdPattern.test(input.candidateId))
+        return { path: null, summary: "invalid candidate identity" };
+    const [state, logs] = await Promise.all([
+        collect(input.runDocker, ["container", "inspect", "--format", "{{json .State}}", input.candidateId]),
+        collect(input.runDocker, ["logs", "--tail", "100", input.candidateId])
+    ]);
+    const health = summarizeState(state.available ? state.text : "", input.secretValues);
+    const summary = health.summary;
+    try {
+        const deploymentDirectory = resolveHomeDeploymentDirectory(input.deploymentName);
+        for (const parent of [resolveSpawnfileHome(), path.dirname(deploymentDirectory), deploymentDirectory]) {
+            const info = await lstat(parent);
+            if (!info.isDirectory() || info.isSymbolicLink() || (info.mode & 0o022) !== 0
+                || (process.getuid && info.uid !== process.getuid()))
+                throw new Error("unsafe diagnostics parent");
+        }
+        const directory = path.join(deploymentDirectory, "diagnostics");
+        await mkdir(directory, { mode: 0o700 }).catch((error) => {
+            if (error.code !== "EEXIST")
+                throw error;
+        });
+        const info = await lstat(directory);
+        if (!info.isDirectory() || info.isSymbolicLink() || (info.mode & 0o777) !== 0o700
+            || (process.getuid && info.uid !== process.getuid()))
+            throw new Error("unsafe diagnostics directory");
+        const destination = path.join(directory, `candidate-${Date.now()}-${randomUUID()}.json`);
+        await writeFile(destination, `${JSON.stringify({
+            version: "spawnfile.candidate-diagnostics.v1", capturedAt: new Date().toISOString(),
+            candidateId: input.candidateId, deployment: input.deploymentName, summary, health,
+            logs: { available: logs.available, text: sanitizeCandidateDiagnostic(logs.text, input.secretValues) }
+        }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+        return { path: destination, summary };
+    }
+    catch {
+        return { path: null, summary };
+    }
+};

package/dist/deployment/dockerLogs.js

@@ -15,10 +15,13 @@ const withDockerTarget = (record, args) => {
     return args;
 };
 const normalizeTail = (tail) => typeof tail === "number" && Number.isInteger(tail) && tail > 0 ? tail : 100;
+const stripTerminalControls = (value) => value.replace(/\x1b\[[0-?]*[ -/]*[@-~]|[\x00-\x08\x0b-\x1f\x7f]/gu, "");
 const redactKnownSecrets = (text, secretValues) => secretValues
+    .map(stripTerminalControls)
     .filter((secret) => secret.length > 0)
+    .sort((left, right) => right.length - left.length)
     .reduce((redacted, secret) => redacted.replaceAll(secret, "[REDACTED]"), text);
-export const redactDockerLogText = (text, secretValues = []) => redactSensitiveText(redactKnownSecrets(text, secretValues));
+export const redactDockerLogText = (text, secretValues = []) => redactSensitiveText(redactKnownSecrets(stripTerminalControls(text), secretValues));
 const combineLogStreams = (stdout, stderr) => {
     if (!stdout) {
         return stderr;