spawnfile 0.1.17 → 0.1.18

package/dist/compiler/workspaceGitFetch.js

@@ -0,0 +1,155 @@
+import { execFile } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { SpawnfileError } from "../shared/index.js";
+const run = promisify(execFile);
+const COMMIT = /^[a-f0-9]{40}$/u;
+const fail = (message) => {
+    throw new SpawnfileError("validation_error", message);
+};
+const shellQuote = (value) => `'${value.replace(/'/g, `'"'"'`)}'`;
+/** The remote ref to fetch, and the commit it must equal when the selector already names one. */
+export const gitPinRefspec = (selector) => {
+    if (selector.kind === "branch")
+        return { source: `refs/heads/${selector.value}` };
+    if (selector.kind === "tag")
+        return { source: `refs/tags/${selector.value}` };
+    if (selector.kind === "ref")
+        return COMMIT.test(selector.value) ? { expected: selector.value, source: selector.value } : { source: selector.value };
+    return { source: "HEAD" };
+};
+/**
+ * Runs `use` with the git environment for one fetch. A key held in an env var
+ * is copied to a private 0600 file in a fresh temporary directory that is
+ * removed afterwards; the key only ever reaches git through `GIT_SSH_COMMAND`.
+ */
+export const withGitPinEnvironment = async (auth, use, environment = process.env) => {
+    // Never prompt, never honour replacement refs: an object id must name its own bytes.
+    const base = { ...environment, GIT_NO_REPLACE_OBJECTS: "1", GIT_TERMINAL_PROMPT: "0" };
+    // The key reaches git and ssh only as a file path, never as an inherited variable.
+    if (auth?.sshKeyEnv !== undefined)
+        delete base[auth.sshKeyEnv];
+    if (auth === undefined)
+        return use(base);
+    let temporary;
+    try {
+        let keyPath;
+        if (auth.sshKeyEnv !== undefined) {
+            const material = environment[auth.sshKeyEnv];
+            if (!material?.trim())
+                fail(`git resource auth env ${auth.sshKeyEnv} is not set`);
+            temporary = await mkdtemp(path.join(os.tmpdir(), "spawnfile-git-key-"));
+            keyPath = path.join(temporary, "key");
+            await writeFile(keyPath, material.endsWith("\n") ? material : `${material}\n`, { mode: 0o600 });
+        }
+        else {
+            keyPath = auth.sshKey;
+            const info = await stat(keyPath).catch(() => undefined);
+            if (!info?.isFile())
+                fail(`git resource ssh_key is not a readable file: ${keyPath}`);
+        }
+        const ssh = `ssh -i ${shellQuote(keyPath)} -o IdentitiesOnly=yes -o BatchMode=yes`;
+        return await use({ ...base, GIT_SSH_COMMAND: ssh });
+    }
+    finally {
+        if (temporary !== undefined)
+            await rm(temporary, { force: true, recursive: true });
+    }
+};
+const git = async (repository, args, env) => {
+    const { stdout } = await run("git", ["-C", repository, ...args], { encoding: "utf8", env, maxBuffer: 16_777_216 });
+    return stdout.trim();
+};
+const LOCK_POLL_MS = 100;
+const processAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+};
+/**
+ * Serializes work on one cache repository across processes on this host: git
+ * keeps one repository-wide `shallow` file, so two shallow fetches into the
+ * same repository can fail each other. A lock whose owner process is gone is
+ * taken over.
+ */
+export const withGitPinLock = async (repository, use) => {
+    const lock = `${repository}.lock`, owner = path.join(lock, "owner");
+    for (;;) {
+        try {
+            await mkdir(lock);
+            await writeFile(owner, `${process.pid}\n`);
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const pid = Number.parseInt(await readFile(owner, "utf8").catch(() => ""), 10);
+            const age = Date.now() - ((await stat(lock).catch(() => undefined))?.mtimeMs ?? Date.now());
+            // An owner-less lock older than a few polls belongs to a process that died between mkdir and write.
+            if (Number.isInteger(pid) ? !processAlive(pid) : age > LOCK_POLL_MS * 50)
+                await rm(lock, { force: true, recursive: true });
+            else
+                await new Promise((resolve) => setTimeout(resolve, LOCK_POLL_MS));
+        }
+    }
+    try {
+        return await use();
+    }
+    finally {
+        await rm(lock, { force: true, recursive: true });
+    }
+};
+/** One bare object cache per remote URL. Auto-gc is off: a concurrent compile may still be reading a commit. Call under the lock. */
+const ensureGitPinRepository = async (repository) => {
+    if (await stat(path.join(repository, "HEAD")).catch(() => undefined))
+        return;
+    await rm(repository, { force: true, recursive: true });
+    await run("git", ["init", "--bare", "-q", repository]);
+    await run("git", ["-C", repository, "config", "gc.auto", "0"]);
+};
+const hasCommit = (repository, commit, env) => git(repository, ["cat-file", "-e", `${commit}^{commit}`], env).then(() => true, () => false);
+/**
+ * Resolves `selector` on `url` to one commit and fetches its objects into the
+ * cache, shallowly, under the repository lock. A full commit id already in the
+ * cache is not fetched again, so a recorded pin rebuilds offline. Any failure
+ * to resolve refuses the compile: a pinned resource never falls back to stale
+ * or empty content.
+ */
+export const fetchGitPin = async (cacheDirectory, url, selector, env) => {
+    await mkdir(cacheDirectory, { mode: 0o700, recursive: true });
+    const repository = path.join(cacheDirectory, `${createHash("sha256").update(url).digest("hex")}.git`);
+    return withGitPinLock(repository, async () => {
+        await ensureGitPinRepository(repository);
+        const { expected, source } = gitPinRefspec(selector);
+        if (expected !== undefined && await hasCommit(repository, expected, env))
+            return { commit: expected, repository };
+        // A per-process ref, so a lock taken over from a dead owner never reads its half-written result.
+        const local = `refs/spawnfile/pins/${process.pid}-${randomBytes(6).toString("hex")}`;
+        try {
+            await git(repository, ["fetch", "--quiet", "--no-tags", "--depth=1", "--", url, `+${source}:${local}`], env);
+            const commit = await git(repository, ["rev-parse", "--verify", `${local}^{commit}`], env);
+            if (!COMMIT.test(commit))
+                fail(`git resource ${url} ${selector.kind} ${selector.value} did not resolve to a commit`);
+            if (expected !== undefined && commit !== expected)
+                fail(`git resource ${url} ref ${expected} resolved to ${commit}`);
+            return { commit, repository };
+        }
+        catch (error) {
+            if (error instanceof SpawnfileError)
+                throw error;
+            const stderr = String(error.stderr ?? "").trim().split("\n").filter(Boolean).pop();
+            const what = selector.kind === "none" ? "default branch" : `${selector.kind} ${selector.value}`;
+            return fail(`git resource ${url} ${what} could not be resolved to a commit${stderr ? `: ${stderr}` : ""}`);
+        }
+        finally {
+            await git(repository, ["update-ref", "-d", local], env).catch(() => undefined);
+        }
+    });
+};

package/dist/compiler/workspaceGitPins.d.ts

@@ -0,0 +1,33 @@
+import type { CompileReportWorkspaceGitResource } from "../report/index.js";
+import { type BundleIdentityMode } from "./workspaceBundleFiles.js";
+import type { MoltnetTargetArchitecture } from "./moltnetReleaseAuthority.js";
+import type { CompilePlan } from "./types.js";
+import type { ResolvedWorkspaceResource } from "./workspaceResources.js";
+type GitResource = Extract<ResolvedWorkspaceResource, {
+    kind: "git";
+}>;
+export interface ResolveWorkspaceGitPinsOptions {
+    outputDirectory: string;
+    architecture?: MoltnetTargetArchitecture;
+    /** The workspace bundle cache directory; git objects and archives live beside it under `git-resources/`. */
+    bundleCacheDirectory?: string;
+    identity?: BundleIdentityMode;
+    environment?: NodeJS.ProcessEnv;
+}
+export interface ResolvedWorkspaceGitPins {
+    /** Digest → archive linked into the Docker context, for `stageWorkspaceBundles`. */
+    built: Map<string, string>;
+    report: CompileReportWorkspaceGitResource[];
+}
+export declare const isBuildPinnedGitResource: (resource: ResolvedWorkspaceResource) => resource is GitResource;
+/**
+ * Lowers every `fetch: build` git resource into a pinned read-only bundle:
+ * the declared branch, tag or ref is resolved on the host to one commit, that
+ * commit's tree is archived deterministically (the same writer as built
+ * bundles), and the agent mounts the archive exactly as it mounts a bundle.
+ * No credential, clone or network access reaches the container. The commit
+ * and archive digest are recorded in the compile report; declaring
+ * `ref: <commit>` reproduces the identical archive.
+ */
+export declare const resolveWorkspaceGitPins: (plan: CompilePlan, options: ResolveWorkspaceGitPinsOptions) => Promise<ResolvedWorkspaceGitPins>;
+export {};

package/dist/compiler/workspaceGitPins.js

@@ -0,0 +1,127 @@
+import os from "node:os";
+import path from "node:path";
+import { SpawnfileError } from "../shared/index.js";
+import { linkBuiltBundle } from "./workspaceBundleArtifacts.js";
+import { lookupCachedBundle, pruneBundleCache, resolveWorkspaceBundleCacheDirectory, storeBuiltBundle } from "./workspaceBundleCache.js";
+import { listCommittedTree } from "./workspaceBundleGit.js";
+import { compileExcludePatterns, writeBundleFiles } from "./workspaceBundleFiles.js";
+import { computeWorkspaceBundleKey, resolveBundleArchitecture } from "./workspaceBundleResolve.js";
+import { normalizeBundleMode } from "./workspaceBundleTar.js";
+import { fetchGitPin, withGitPinEnvironment } from "./workspaceGitFetch.js";
+const SYMLINK = 0o120000, GITLINK = 0o160000;
+const fail = (message) => {
+    throw new SpawnfileError("validation_error", message);
+};
+export const isBuildPinnedGitResource = (resource) => resource.kind === "git" && resource.fetch === "build";
+const selectorOf = (resource) => resource.branch ? { kind: "branch", value: resource.branch.trim() }
+    : resource.tag ? { kind: "tag", value: resource.tag.trim() }
+        : resource.ref ? { kind: "ref", value: resource.ref.trim() }
+            : { kind: "none", value: "" };
+const expandPath = (value, base) => value === "~" || value.startsWith("~/") ? path.join(os.homedir(), value.slice(1)) : path.resolve(base, value);
+const authOf = (resource) => {
+    if (!resource.auth)
+        return undefined;
+    return resource.auth.ssh_key !== undefined
+        ? { sshKey: expandPath(resource.auth.ssh_key, path.dirname(resource.scope.key)) }
+        : { sshKeyEnv: resource.auth.ssh_key_env };
+};
+const declarationKey = (resource) => JSON.stringify({
+    auth: authOf(resource) ?? null, exclude: resource.exclude ?? null, selector: selectorOf(resource), url: resource.url.trim()
+});
+/** The committed tree as bundle entries: blob ids and modes only, under the same safety rules as built bundles. */
+const treeEntries = async (resource, repository, commit) => {
+    const excluded = compileExcludePatterns(resource.exclude);
+    const entries = [];
+    for (const entry of await listCommittedTree(repository, commit)) {
+        if (excluded(entry.path))
+            continue;
+        if (entry.mode === SYMLINK)
+            fail(`Workspace git resource ${resource.id} contains a symlink; exclude it: ${entry.path}`);
+        if (entry.mode === GITLINK)
+            fail(`Workspace git resource ${resource.id} contains a submodule; exclude it: ${entry.path}`);
+        if (entry.type !== "blob")
+            fail(`Workspace git resource ${resource.id} has unsupported git type ${entry.type}: ${entry.path}`);
+        if (!entry.path || entry.path.includes("\\") || entry.path.split("/").some((part) => !part || part === "." || part === "..")) {
+            fail(`Workspace git resource ${resource.id} path cannot be archived safely: ${entry.path}`);
+        }
+        entries.push({ identity: `git:${entry.objectId}`, mode: normalizeBundleMode(entry.mode), objectId: entry.objectId, path: entry.path });
+    }
+    if (entries.length === 0)
+        fail(`Workspace git resource ${resource.id} has no files at ${commit}`);
+    return entries.sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0));
+};
+/**
+ * Lowers every `fetch: build` git resource into a pinned read-only bundle:
+ * the declared branch, tag or ref is resolved on the host to one commit, that
+ * commit's tree is archived deterministically (the same writer as built
+ * bundles), and the agent mounts the archive exactly as it mounts a bundle.
+ * No credential, clone or network access reaches the container. The commit
+ * and archive digest are recorded in the compile report; declaring
+ * `ref: <commit>` reproduces the identical archive.
+ */
+export const resolveWorkspaceGitPins = async (plan, options) => {
+    const result = { built: new Map(), report: [] };
+    const recording = plan.nodes.some((node) => node.kind === "agent" && node.value.training?.record !== undefined);
+    const pinned = plan.nodes.flatMap((node) => node.kind === "agent" ? (node.value.workspaceResources ?? []).filter(isBuildPinnedGitResource) : []);
+    if (pinned.length === 0)
+        return result;
+    const root = path.join(path.dirname(resolveWorkspaceBundleCacheDirectory(options.bundleCacheDirectory)), "git-resources");
+    const objects = path.join(root, "objects"), archives = path.join(root, "archives");
+    const platform = `linux/${resolveBundleArchitecture(options.architecture)}`, identity = options.identity ?? "dev";
+    const resolved = new Map(), usedKeys = new Set();
+    for (const resource of pinned) {
+        const memoKey = declarationKey(resource);
+        if (resolved.has(memoKey))
+            continue;
+        const selector = selectorOf(resource), auth = authOf(resource), url = resource.url.trim();
+        const { commit, repository } = await withGitPinEnvironment(auth, (env) => fetchGitPin(objects, url, selector, env), options.environment);
+        const entries = await treeEntries(resource, repository, commit);
+        const key = computeWorkspaceBundleKey({ entries }, platform);
+        usedKeys.add(key);
+        let cached = await lookupCachedBundle(archives, key), staged = cached && await linkBuiltBundle(cached.tarPath, options.outputDirectory, cached.sha256);
+        if (!cached || !staged) {
+            cached = await storeBuiltBundle(archives, key, (temporaryPath) => writeBundleFiles({ directory: repository, entries, mode: "release" }, temporaryPath));
+            staged = await linkBuiltBundle(cached.tarPath, options.outputDirectory, cached.sha256);
+            if (!staged)
+                throw new SpawnfileError("compile_error", `Workspace git resource archive vanished from the cache while it was staged: ${key}`);
+        }
+        result.built.set(cached.sha256, staged);
+        resolved.set(memoKey, {
+            commit,
+            facts: {
+                auth: auth === undefined ? "none" : auth.sshKey !== undefined ? "ssh_key" : "ssh_key_env",
+                cache_key: key, commit, content_bytes: cached.contentBytes, file_count: cached.fileCount, id: resource.id, identity,
+                platform, selector: selector.kind === "none" ? { kind: "default_branch" } : { kind: selector.kind, value: selector.value },
+                sha256: cached.sha256, url
+            }
+        });
+    }
+    for (const node of plan.nodes) {
+        if (node.kind !== "agent" || !node.value.workspaceResources?.some(isBuildPinnedGitResource))
+            continue;
+        node.value.workspaceResources = node.value.workspaceResources.map((resource) => {
+            if (!isBuildPinnedGitResource(resource))
+                return resource;
+            const { facts } = resolved.get(declarationKey(resource));
+            const same = (existing) => existing.id === resource.id && existing.url === facts.url && existing.commit === facts.commit && existing.sha256 === facts.sha256 && JSON.stringify(existing.selector) === JSON.stringify(facts.selector);
+            if (recording) {
+                const declared_by = plan.nodes.find((entry) => entry.value.source === resource.scope.key)?.id;
+                let pin = result.report.find((entry) => same(entry) && entry.declared_by === declared_by);
+                if (!pin) {
+                    pin = { ...facts, id: resource.id, agent_node_ids: [], ...(declared_by ? { declared_by } : {}) };
+                    result.report.push(pin);
+                }
+                if (!pin.agent_node_ids.includes(node.id))
+                    pin.agent_node_ids.push(node.id);
+                pin.agent_node_ids.sort();
+            }
+            else if (!result.report.some(same))
+                result.report.push({ ...facts, id: resource.id });
+            // From here on it is a bundle: same staging, same identity-checked read-only mount, no auth fields.
+            return { id: resource.id, kind: "bundle", mode: "readonly", mount: resource.mount, scope: resource.scope, sha256: facts.sha256, sharing: "per_agent" };
+        });
+    }
+    await pruneBundleCache(archives, usedKeys);
+    result.report.sort((left, right) => left.id.localeCompare(right.id) || left.url.localeCompare(right.url) || left.commit.localeCompare(right.commit) || left.sha256.localeCompare(right.sha256));
+    return result;
+};

package/dist/compiler/workspaceResources.d.ts

@@ -1,4 +1,4 @@
-import type { TeamWorkspaceResource } from "../manifest/index.js";
+import type { TeamWorkspaceResource, WorkspaceBundleBuild } from "../manifest/index.js";
 export type WorkspaceResourceSharing = "per_agent" | "team";
 export interface WorkspaceResourceScope {
     kind: "agent" | "team";
@@ -26,6 +26,10 @@ export interface WorkspaceResourcePlan {
     tag?: string;
     url?: string;
 }
+/** Multi-agent runtime targets retain one resource identity per source agent. */
+export declare const workspaceResourceTargetId: (targetId: string, sourceId: string, sourceCount: number) => string;
+/** A bundle build declaration with every relative path resolved against the declaring manifest's directory. */
+export declare const resolveBundleBuildPaths: (build: WorkspaceBundleBuild, base: string) => WorkspaceBundleBuild;
 export declare const mergeWorkspaceResources: (inherited: ResolvedWorkspaceResource[] | undefined, local: TeamWorkspaceResource[] | undefined, ownerName: string, ownerScope: WorkspaceResourceScope) => ResolvedWorkspaceResource[];
 export declare const toWorkspaceResourcePlan: (resource: ResolvedWorkspaceResource, context: {
     targetId: string;

package/dist/compiler/workspaceResources.js

@@ -1,6 +1,8 @@
 import path from "node:path";
 import { SpawnfileError } from "../shared/index.js";
 import { createShortHash, slugify } from "./helpers.js";
+/** Multi-agent runtime targets retain one resource identity per source agent. */
+export const workspaceResourceTargetId = (targetId, sourceId, sourceCount) => sourceCount > 1 ? `${targetId}:${sourceId}` : targetId;
 const normalizeMount = (value) => {
     const trimmed = value.trim();
     const workspaceRelative = trimmed.startsWith("${workspace}/")
@@ -13,12 +15,29 @@ const normalizeMount = (value) => {
     }
     return collapsed.length > 1 ? collapsed.replace(/\/+$/u, "") : "/";
 };
+/** A bundle build declaration with every relative path resolved against the declaring manifest's directory. */
+export const resolveBundleBuildPaths = (build, base) => {
+    const files = (input) => ({ ...input, root: path.resolve(base, input.root) });
+    if (build.files)
+        return { files: files(build.files) };
+    if (build.dependencies)
+        return { dependencies: { ...build.dependencies, directory: path.resolve(base, build.dependencies.directory) } };
+    const generated = build.generated;
+    return { generated: { ...generated, cwd: path.resolve(base, generated.cwd ?? "."), inputs: generated.inputs.map(files) } };
+};
 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 === "bundle") {
+        // Relative paths compare as resolved against their declaring manifest: the same text in two directories is two inputs.
+        const base = path.dirname(resource.scope.key);
+        const build = resource.build && resolveBundleBuildPaths(resource.build, base);
+        return JSON.stringify({ build: build ?? null, kind: resource.kind, mode: resource.mode, mount: normalizeMount(resource.mount), sha256: resource.sha256 ?? null, source: resource.source === undefined ? null : path.resolve(base, resource.source), sharing: resource.sharing });
+    }
     if (resource.kind === "git") {
         return JSON.stringify({
+            auth: resource.auth ?? null,
             branch: resource.branch?.trim() ?? "",
+            exclude: resource.exclude ?? null,
+            fetch: resource.fetch ?? "start",
             kind: "git",
             mode: resource.mode,
             mount: normalizeMount(resource.mount),
@@ -29,6 +48,8 @@ const normalizeResourceIdentity = (resource) => {
         });
     }
     return JSON.stringify({
+        // Feed paths resolve against the declaring manifest, like bundle inputs.
+        ...(resource.feed ? { feed: { ...resource.feed, base: path.dirname(resource.scope.key) } } : {}),
         kind: "volume",
         mode: resource.mode,
         mount: normalizeMount(resource.mount),
@@ -88,6 +109,12 @@ export const mergeWorkspaceResources = (inherited = [], local = [], ownerName, o
     }
     return merged.sort((left, right) => left.id.localeCompare(right.id));
 };
+/** A bundle's digest exists only after `resolveWorkspaceBundles` built or hashed it. */
+const resolvedBundleDigest = (resource) => {
+    if (resource.sha256 === undefined)
+        throw new SpawnfileError("compile_error", `Workspace bundle ${resource.id} has not been built`);
+    return resource.sha256;
+};
 export const toWorkspaceResourcePlan = (resource, context) => resource.kind === "git"
     ? {
         backingPath: resolveBackingPath(resource, context.targetId),
@@ -103,11 +130,11 @@ export const toWorkspaceResourcePlan = (resource, context) => resource.kind ===
         url: resource.url
     }
     : resource.kind === "bundle" ? {
-        archivePath: `/opt/spawnfile/workspace-bundles/${resource.sha256.slice(7)}.tar`,
+        archivePath: `/opt/spawnfile/workspace-bundles/${resolvedBundleDigest(resource).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)
+        mount: normalizeMount(resource.mount), sharing: resource.sharing, sha256: resolvedBundleDigest(resource),
+        ...(resource.source !== undefined ? { source: path.resolve(path.dirname(resource.scope.key), resource.source) } : {})
     } : {
         backingPath: resolveBackingPath(resource, context.targetId),
         id: resource.id,

package/dist/deployment/activation.d.ts

@@ -0,0 +1,3 @@
+import type { DeploymentActivation } from "./resourceLog.js";
+/** Strictly later than the stopped observation, even at millisecond clock resolution. */
+export declare const activationBeforeStart: (stoppedAt: number | undefined, now?: () => Date) => Promise<DeploymentActivation>;

package/dist/deployment/activation.js

@@ -0,0 +1,12 @@
+import { setTimeout } from "node:timers/promises";
+/** Strictly later than the stopped observation, even at millisecond clock resolution. */
+export const activationBeforeStart = async (stoppedAt, now = () => new Date()) => {
+    for (let attempt = 0; attempt < 1_000; attempt += 1) {
+        const instant = now();
+        if (stoppedAt === undefined || instant.getTime() > stoppedAt) {
+            return { activated_at: instant.toISOString(), activation_exact: true };
+        }
+        await setTimeout(1);
+    }
+    throw new Error("Host clock did not advance after the previous container stopped");
+};

package/dist/deployment/canaryCutover.d.ts

@@ -5,8 +5,8 @@ export declare const deploymentIdentitySchema: z.ZodObject<{
     fingerprint: z.ZodString;
     deployment_name: z.ZodString;
     deployment_mode: z.ZodEnum<{
-        project: "project";
         image: "image";
+        project: "project";
     }>;
     image_id: z.ZodString;
     organization_unit_id: z.ZodString;

package/dist/deployment/candidateRecording.d.ts

@@ -0,0 +1,8 @@
+import { type DeploymentActivation, type DeployResourceReport, type DeployResources } from "./resourceLog.js";
+/** A candidate may execute turns before failing readiness/publication. Preserve its pins
+ * after rollback, without replacing the still-authoritative predecessor's record. */
+export declare const recordDeploymentRollback: (recordPath: string, record: DeploymentActivation & {
+    name: string;
+    created_at: string;
+    resource_snapshot?: DeployResources;
+}, report: DeployResourceReport, reportBytes: string, rolledBackAt: string) => Promise<void>;

package/dist/deployment/candidateRecording.js

@@ -0,0 +1,22 @@
+import path from "node:path";
+import { ensureDirectory } from "../filesystem/index.js";
+import { acquirePidLock } from "./pidLock.js";
+import { createDeployResources, ensureDeployResources } from "./resourceLog.js";
+/** A candidate may execute turns before failing readiness/publication. Preserve its pins
+ * after rollback, without replacing the still-authoritative predecessor's record. */
+export const recordDeploymentRollback = async (recordPath, record, report, reportBytes, rolledBackAt) => {
+    if (!report.recording)
+        return;
+    await ensureDirectory(path.dirname(recordPath));
+    const release = await acquirePidLock(`${recordPath}.resource-log.lock`);
+    try {
+        ensureDeployResources(recordPath, {
+            ...(record.resource_snapshot ?? createDeployResources(recordPath, record, report, reportBytes)),
+            rolled_back_at: rolledBackAt, activation_exact: false, exact: false,
+            activation_note: "Candidate ran before rollback; its turns cannot be distinguished from predecessor turns"
+        }, report.recording.keep_ms);
+    }
+    finally {
+        await release();
+    }
+};

package/dist/deployment/dockerManager.d.ts

@@ -1,5 +1,6 @@
 import type { DeploymentRecordSource } from "./record.js";
 import type { OrganizationReadinessEvidence } from "../compiler/organizationReadyEvidence.js";
+import type { DeploymentActivation, DeployResourceReport } from "./resourceLog.js";
 import { type DockerProbeExecFile } from "./dockerProbeGateway.js";
 import { type OrganizationReadiness } from "./organizationReady.js";
 import { type DockerDeploymentTarget, type DockerTargetExecFile } from "./target.js";
@@ -22,7 +23,7 @@ export interface DockerDeploymentRunInvocationInput {
     dockerContext?: string | null;
     dockerHost?: string | null;
 }
-export interface DockerDeploymentReportInput {
+export interface DockerDeploymentReportInput extends DeployResourceReport {
     compile_fingerprint?: string;
     container?: {
         moltnet?: {
@@ -38,7 +39,7 @@ export interface DockerDeploymentReportInput {
     nodes: DockerDeploymentNodeInput[];
     root: string;
 }
-export interface WriteDockerDeploymentRecordInput {
+export interface WriteDockerDeploymentRecordInput extends DeploymentActivation {
     authProfileName: string | null;
     compileFingerprint: string;
     containerName: string | null;
@@ -82,7 +83,8 @@ export declare const createDockerDeploymentUnitId: (deploymentName: string) => s
 export declare const createDockerDeploymentRecord: (input: WriteDockerDeploymentRecordInput) => DeploymentRecord;
 export declare const createDockerProjectLabel: (projectRoot: string, projectName?: string) => string;
 export declare const writeDockerDeploymentRecord: (input: WriteDockerDeploymentRecordInput) => Promise<string>;
-export declare const writeDockerDeploymentRecordForRun: (input: {
+export declare const writeDockerDeploymentRecordForRun: (input: DeploymentActivation & {
+    previousRecord?: DeploymentRecord;
     authProfileName: string | null;
     envFilePath?: string;
     imageTag: string;

package/dist/deployment/dockerManager.js

@@ -3,7 +3,10 @@ import { normalizeProjectLabelSlug } from "../distribution/index.js";
 import { resolveNoopolisRunId } from "../runtime/index.js";
 import { SpawnfileError } from "../shared/index.js";
 import { inspectDockerDeployment } from "./dockerInspect.js";
-import { normalizeDeploymentName } from "./names.js";
+import { bindDeploymentRecording } from "./recordPublication.js";
+import { readUtf8File } from "../filesystem/index.js";
+import { REPORT_FILENAME } from "../shared/index.js";
+import { normalizeDeploymentName, resolveDeploymentRecordPath } from "./names.js";
 import { createDockerProbeGateway } from "./dockerProbeGateway.js";
 import { organizationReadinessFromProbeError, reconcileOrganizationReadiness } from "./organizationReady.js";
 import { resolveDockerDeploymentTarget } from "./target.js";
@@ -40,6 +43,7 @@ export const createDockerDeploymentRecord = (input) => {
         auth_profile: input.authProfileName,
         compile_fingerprint: input.compileFingerprint,
         created_at: new Date().toISOString(),
+        ...(input.activated_at ? { activated_at: input.activated_at, activation_exact: input.activation_exact, activation_note: input.activation_note } : {}),
         ...(input.envFilePath ? { env_file: path.resolve(input.envFilePath) } : {}),
         manager: "docker",
         name,
@@ -85,7 +89,8 @@ export const writeDockerDeploymentRecordForRun = async (input) => {
     if (!input.invocation.detach || !input.invocation.deploymentName) {
         return null;
     }
-    return writeDockerDeploymentRecord({
+    const record = createDockerDeploymentRecord({
+        activated_at: input.activated_at, activation_exact: input.activation_exact, activation_note: input.activation_note,
         authProfileName: input.authProfileName,
         compileFingerprint: requireCompileFingerprint(input.report.compile_fingerprint),
         containerName: input.invocation.containerName,
@@ -116,6 +121,11 @@ export const writeDockerDeploymentRecordForRun = async (input) => {
             timeoutMs: input.targetTimeoutMs
         })
     });
+    const recordPath = resolveDeploymentRecordPath(input.outputDirectory, record.name);
+    const bound = input.report.recording
+        ? bindDeploymentRecording(recordPath, record, input.report, await readUtf8File(path.join(input.outputDirectory, REPORT_FILENAME)))
+        : record;
+    return writeDeploymentRecord(input.outputDirectory, bound, input.previousRecord);
 };
 const recordCorrelation = (record) => ({
     compileFingerprint: record.compile_fingerprint,

package/dist/deployment/downDeployment.d.ts

@@ -21,6 +21,8 @@ export interface DownDeploymentOptions {
      * folder rule — this is the only reversible-by-default lifecycle boundary spawnfile
      * has: containers are cheap to recreate, the durable stores are not). */
     removeVolumes?: boolean;
+    /** Explicitly permits deleting memory ledgers used by recording agents. */
+    discardRecordedMemory?: boolean;
     expectedLifecycleCorrelation?: DeploymentLifecycleCorrelation;
     timeoutMs?: number;
 }

package/dist/deployment/downDeployment.js

@@ -8,6 +8,7 @@ import { defaultDockerTeardownExecFile, removeDockerContainer, removeDockerVolum
 import { DOWN_RECEIPT_VERSION } from "./downReceiptTypes.js";
 import { initializeOrganizationHandoffAuthorityStore, } from "./organizationHandoffAuthorityStore.js";
 import { readDeploymentRecordFromOutput } from "./record.js";
+import { assertRecordedMemoryRetention, recordedMemoryForDeletion } from "./recordedMemoryRetention.js";
 import { readHomeDeploymentRecord, readHomeDeploymentReport, resolveHomeRecordPath } from "./homeStore.js";
 import { resolveDeploymentRecordPath } from "./names.js";
 import { dockerContextNameForTarget } from "./target.js";
@@ -70,6 +71,7 @@ const imageDown = async (record, options, runner) => {
     if (report.compile_fingerprint !== record.compile_fingerprint)
         throw new SpawnfileError("runtime_error", "Cached image distribution report does not match its deployment record");
     const { owned, skipped } = partitionDeclaredVolumes(report.persistent_mounts, (mount) => derivePersistentMountVolumeName(record.name, mount));
+    assertRecordedMemoryRetention(recordedMemoryForDeletion(record, report, report.persistent_mounts, options), report.persistent_mounts, owned, (mount) => derivePersistentMountVolumeName(record.name, mount), options);
     const volumes = [...owned, ...skipped].sort();
     const removed = await removeDockerContainer(record.target, unit.container_id, runner);
     if (!removed.removed)
@@ -198,6 +200,10 @@ export const downDeployment = async (options) => {
     const runnerOptions = { dockerCommand, execFile: execFileImpl, timeoutMs };
     if (resolved.mode === "image")
         return imageDown(initialRecord, options, runnerOptions);
+    const report = await readCompileReport(compiledOutputDirectory);
+    const mounts = report?.container?.persistent_mounts ?? [];
+    const { owned, skipped } = partitionDeclaredVolumes(mounts, (mount) => mount.volume_name);
+    assertRecordedMemoryRetention(recordedMemoryForDeletion(initialRecord, report, mounts, options), mounts, owned, (mount) => mount.volume_name, options);
     const record = await ensureExported(initialRecord, {
         ...options,
         compiledOutputDirectory,
@@ -220,8 +226,6 @@ export const downDeployment = async (options) => {
             errors.push(`unable to remove container ${containerRef} (unit ${unit.id}): ${outcome.error}`);
         }
     }
-    const report = await readCompileReport(compiledOutputDirectory);
-    const { owned, skipped } = partitionDeclaredVolumes(report?.container?.persistent_mounts ?? [], (mount) => mount.volume_name);
     // Declared volumes are retained unconditionally: they are shared project
     // state, not this deployment's, so `--volumes` must never destroy them.
     const retainedVolumes = [...skipped];

package/dist/deployment/homeStore.d.ts

@@ -1,12 +1,20 @@
 import type { DistributionReport } from "../distribution/index.js";
 import { type DeploymentRecord } from "./record.js";
+export { HomeDeploymentRecordingError } from "./recordPublication.js";
 export declare const resolveHomeDeploymentsDirectory: () => string;
 export declare const resolveHomeDeploymentDirectory: (deploymentName: string) => string;
 export declare const resolveHomeRecordPath: (deploymentName: string) => string;
 export declare const resolveHomeReportPath: (deploymentName: string) => string;
+/**
+ * Acquires an exclusive lock for a home deployment so concurrent `up`
+ * invocations (and a drained release holding it across its swap) cannot race
+ * on the same record or orphan each other's containers. Returns a release
+ * function. Throws if a live operation holds the lock; a lock left by a
+ * process that is gone is reclaimed. See `pidLock.ts`.
+ */
 export declare const acquireHomeDeploymentLock: (deploymentName: string) => Promise<() => Promise<void>>;
 /** Writes the record and the cached distribution report together, record last. */
-export declare const writeHomeDeployment: (record: DeploymentRecord, report: DistributionReport) => Promise<{
+export declare const writeHomeDeployment: (record: DeploymentRecord, report: DistributionReport, previous?: DeploymentRecord | null) => Promise<{
     recordPath: string;
     reportPath: string;
 }>;