spawnfile 0.1.13 → 0.1.17

package/dist/deployment/lifecycleCompletionRoot.js

@@ -0,0 +1,243 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath } from "node:fs/promises";
+import path from "node:path";
+import { resolveSpawnfileHome } from "../auth/index.js";
+import { failLifecycleStore } from "./lifecycleCompletionPaths.js";
+const OWNER = process.getuid?.() ?? -1;
+const authorities = new Map();
+const chain = (value) => {
+    const parsed = path.parse(value);
+    const result = [parsed.root];
+    let current = parsed.root;
+    for (const part of value.slice(parsed.root.length).split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        result.push(current);
+    }
+    return result;
+};
+const isKnownDarwinAlias = async (value) => {
+    if (process.platform !== "darwin" || (value !== "/var" && value !== "/tmp"))
+        return false;
+    const resolved = await realpath(value).catch(() => "");
+    return resolved === (value === "/var" ? "/private/var" : "/private/tmp");
+};
+const validateConfiguredAliases = async (configuredHome, canonicalHome) => {
+    for (const value of chain(configuredHome)) {
+        const info = await lstat(value).catch(() => failLifecycleStore("unsafe root"));
+        if (info.isSymbolicLink()) {
+            if (info.uid !== 0 || (info.mode & 0o022) !== 0 || !(await isKnownDarwinAlias(value))) {
+                failLifecycleStore("unsafe root");
+            }
+        }
+        else if (!info.isDirectory()) {
+            failLifecycleStore("unsafe root");
+        }
+    }
+    if ((await realpath(configuredHome).catch(() => "")) !== canonicalHome) {
+        failLifecycleStore("root changed");
+    }
+};
+const captureCanonicalChain = async (canonicalHome, root) => {
+    const identities = [];
+    for (const value of chain(root)) {
+        const info = await lstat(value).catch(() => failLifecycleStore("unsafe root"));
+        const writable = (info.mode & 0o022) !== 0;
+        const stickyRootTemp = info.uid === 0 && writable && (info.mode & 0o1000) !== 0;
+        if (!info.isDirectory() ||
+            info.isSymbolicLink() ||
+            (info.uid !== OWNER && info.uid !== 0) ||
+            (writable && !stickyRootTemp))
+            failLifecycleStore("unsafe root");
+        if ((value === canonicalHome || value === root) &&
+            (info.uid !== OWNER || (info.mode & 0o777) !== 0o700))
+            failLifecycleStore("unsafe root");
+        identities.push({ dev: info.dev, ino: info.ino, path: value });
+    }
+    return identities;
+};
+const revalidateIdentities = async (identities) => {
+    for (const expected of identities) {
+        const current = await lstat(expected.path).catch(() => failLifecycleStore("root changed"));
+        const writable = (current.mode & 0o022) !== 0;
+        const stickyRootTemp = current.uid === 0 && writable && (current.mode & 0o1000) !== 0;
+        if (!current.isDirectory() ||
+            current.isSymbolicLink() ||
+            (current.uid !== OWNER && current.uid !== 0) ||
+            (writable && !stickyRootTemp))
+            failLifecycleStore("unsafe root");
+        if (current.dev !== expected.dev || current.ino !== expected.ino) {
+            failLifecycleStore("root changed");
+        }
+    }
+};
+const captureSafeExistingChain = async (value) => {
+    const identities = [];
+    for (const current of chain(value)) {
+        const info = await lstat(current).catch(() => failLifecycleStore("unsafe root"));
+        const writable = (info.mode & 0o022) !== 0;
+        const stickyRootTemp = info.uid === 0 && writable && (info.mode & 0o1000) !== 0;
+        if (!info.isDirectory() ||
+            info.isSymbolicLink() ||
+            (info.uid !== OWNER && info.uid !== 0) ||
+            (writable && !stickyRootTemp))
+            failLifecycleStore("unsafe root");
+        identities.push({ dev: info.dev, ino: info.ino, path: current });
+    }
+    return identities;
+};
+const resolveOrCreateConfiguredHome = async (configuredHome, create) => {
+    const logical = chain(configuredHome);
+    let existing = logical[0];
+    let missingAt = logical.length;
+    for (let index = 0; index < logical.length; index += 1) {
+        const current = logical[index];
+        let info;
+        try {
+            info = await lstat(current);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                failLifecycleStore("unsafe root");
+            missingAt = index;
+            break;
+        }
+        if (info.isSymbolicLink()) {
+            if (info.uid !== 0 || (info.mode & 0o022) !== 0 || !(await isKnownDarwinAlias(current))) {
+                failLifecycleStore("unsafe root");
+            }
+        }
+        else if (!info.isDirectory()) {
+            failLifecycleStore("unsafe root");
+        }
+        existing = current;
+    }
+    if (missingAt === logical.length) {
+        return realpath(configuredHome).catch(() => failLifecycleStore("unsafe root"));
+    }
+    if (!create)
+        return null;
+    let canonicalParent = await realpath(existing).catch(() => failLifecycleStore("unsafe root"));
+    let identities = await captureSafeExistingChain(canonicalParent);
+    for (let index = missingAt; index < logical.length; index += 1) {
+        const name = path.basename(logical[index]);
+        const next = path.join(canonicalParent, name);
+        await revalidateIdentities(identities);
+        await mkdir(next, { mode: 0o700 }).catch((error) => {
+            if (error.code !== "EEXIST")
+                failLifecycleStore("unsafe root");
+        });
+        await revalidateIdentities(identities);
+        const created = await lstat(next).catch(() => failLifecycleStore("unsafe root"));
+        if (!created.isDirectory() ||
+            created.isSymbolicLink() ||
+            created.uid !== OWNER ||
+            (created.mode & 0o777) !== 0o700)
+            failLifecycleStore("unsafe root");
+        canonicalParent = next;
+        identities = [...identities, { dev: created.dev, ino: created.ino, path: next }];
+    }
+    return canonicalParent;
+};
+export const revalidateLifecycleRootAuthority = async (authority) => {
+    await validateConfiguredAliases(authority.configuredHome, authority.canonicalHome);
+    for (const expected of authority.identities) {
+        const current = await lstat(expected.path).catch(() => failLifecycleStore("root changed"));
+        const writable = (current.mode & 0o022) !== 0;
+        const stickyRootTemp = current.uid === 0 && writable && (current.mode & 0o1000) !== 0;
+        if (!current.isDirectory() ||
+            current.isSymbolicLink() ||
+            (current.uid !== OWNER && current.uid !== 0) ||
+            (writable && !stickyRootTemp) ||
+            ((expected.path === authority.canonicalHome || expected.path === authority.root) &&
+                (current.uid !== OWNER || (current.mode & 0o777) !== 0o700)))
+            failLifecycleStore("unsafe root");
+        if (current.dev !== expected.dev || current.ino !== expected.ino) {
+            failLifecycleStore("root changed");
+        }
+    }
+};
+export const validateLifecycleRoot = async (create) => {
+    const configuredHome = resolveSpawnfileHome();
+    const cached = authorities.get(configuredHome);
+    if (cached) {
+        await revalidateLifecycleRootAuthority(cached);
+        return cached;
+    }
+    const canonicalHome = await resolveOrCreateConfiguredHome(configuredHome, create);
+    if (canonicalHome === null)
+        return null;
+    await validateConfiguredAliases(configuredHome, canonicalHome);
+    const homeIdentities = await captureSafeExistingChain(canonicalHome);
+    const homeInfo = await lstat(canonicalHome).catch(() => failLifecycleStore("unsafe root"));
+    if (homeInfo.uid !== OWNER || (homeInfo.mode & 0o777) !== 0o700) {
+        failLifecycleStore("unsafe root");
+    }
+    const root = path.join(canonicalHome, "lifecycle-completions");
+    if (create) {
+        await revalidateIdentities(homeIdentities);
+        await mkdir(root, { mode: 0o700 }).catch((error) => {
+            if (error.code !== "EEXIST")
+                failLifecycleStore("unsafe root");
+        });
+        await revalidateIdentities(homeIdentities);
+    }
+    else {
+        try {
+            await lstat(root);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return null;
+            failLifecycleStore("unsafe root");
+        }
+    }
+    const authority = {
+        canonicalHome,
+        configuredHome,
+        identities: await captureCanonicalChain(canonicalHome, root),
+        root
+    };
+    const prior = authorities.get(configuredHome);
+    if (prior) {
+        await revalidateLifecycleRootAuthority(prior);
+        return prior;
+    }
+    authorities.set(configuredHome, authority);
+    return authority;
+};
+export const lifecycleRoot = async () => (await validateLifecycleRoot(true))?.root ?? failLifecycleStore("unsafe root");
+export const existingLifecycleRoot = async () => (await validateLifecycleRoot(false))?.root ?? null;
+export const requireLifecycleRootAuthority = async () => (await validateLifecycleRoot(true)) ?? failLifecycleStore("unsafe root");
+export const openLifecycleAuthorityRoot = async (authority) => {
+    await revalidateLifecycleRootAuthority(authority);
+    const handle = await open(authority.root, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW).catch(() => failLifecycleStore("root changed"));
+    const expected = authority.identities.at(-1);
+    const info = await handle.stat();
+    if (info.dev !== expected.dev || info.ino !== expected.ino) {
+        await handle.close().catch(() => undefined);
+        failLifecycleStore("root changed");
+    }
+    return handle;
+};
+export const revalidateHeldLifecycleRoot = async (authority, handle) => {
+    const expected = authority.identities.at(-1);
+    const info = await handle.stat();
+    if (info.dev !== expected.dev || info.ino !== expected.ino)
+        failLifecycleStore("root changed");
+    await revalidateLifecycleRootAuthority(authority);
+};
+export const syncLifecycleDirectory = async (directory) => {
+    const authority = await requireLifecycleRootAuthority();
+    if (path.resolve(directory) !== authority.root)
+        failLifecycleStore("unsafe root");
+    const handle = await openLifecycleAuthorityRoot(authority);
+    try {
+        await revalidateHeldLifecycleRoot(authority, handle);
+        await handle.sync();
+        await revalidateHeldLifecycleRoot(authority, handle);
+    }
+    finally {
+        await handle.close();
+    }
+    await revalidateLifecycleRootAuthority(authority);
+};

package/dist/deployment/lifecycleCompletionStore.d.ts

@@ -0,0 +1,6 @@
+export { admissionPath, evidencePath, failLifecycleStore, heartbeatPath, lifecycleRecordName, planPath, recoveryPath, upCleanupPath, upReservationPath, upStartPath, resolveLifecycleCompletionDirectory, resolveLifecycleCompletionPath } from "./lifecycleCompletionPaths.js";
+export { existingLifecycleRoot, lifecycleRoot, syncLifecycleDirectory } from "./lifecycleCompletionRoot.js";
+export type LifecycleStoreTestHookPoint = "before_missing_return" | "before_record_open" | "before_publish_link" | "before_publish_temp_open" | "before_publish_unlink";
+export declare const setLifecycleStoreTestHook: (hook: ((point: LifecycleStoreTestHookPoint) => Promise<void> | void) | null) => void;
+export declare const readLifecycleRecord: (file: string, links?: readonly number[]) => Promise<string | null>;
+export declare const publishLifecycleRecord: (directory: string, file: string, content: string, existing?: "ignore" | "match") => Promise<boolean>;

package/dist/deployment/lifecycleCompletionStore.js

@@ -0,0 +1,151 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { link, lstat, open, unlink } from "node:fs/promises";
+import path from "node:path";
+import { LIFECYCLE_RECORD_MAX_BYTES } from "./lifecycleCompletionContracts.js";
+import { failLifecycleStore, resolveLifecycleCompletionDirectory } from "./lifecycleCompletionPaths.js";
+import { openLifecycleAuthorityRoot, requireLifecycleRootAuthority, revalidateHeldLifecycleRoot, revalidateLifecycleRootAuthority, syncLifecycleDirectory, validateLifecycleRoot } from "./lifecycleCompletionRoot.js";
+import { matchesSettledLifecyclePublication, readSettledLifecycleRecord, settleLifecyclePublicationUntil } from "./lifecycleCompletionPublication.js";
+export { admissionPath, evidencePath, failLifecycleStore, heartbeatPath, lifecycleRecordName, planPath, recoveryPath, upCleanupPath, upReservationPath, upStartPath, resolveLifecycleCompletionDirectory, resolveLifecycleCompletionPath } from "./lifecycleCompletionPaths.js";
+export { existingLifecycleRoot, lifecycleRoot, syncLifecycleDirectory } from "./lifecycleCompletionRoot.js";
+const OWNER = process.getuid?.() ?? -1;
+let testHook = null;
+export const setLifecycleStoreTestHook = (hook) => {
+    testHook = hook;
+};
+const runTestHook = async (point) => {
+    await testHook?.(point);
+};
+const canonicalRecordPath = (file, authority) => {
+    const directory = path.dirname(path.resolve(file));
+    const configuredRoot = resolveLifecycleCompletionDirectory();
+    if (directory !== authority.root && directory !== configuredRoot) {
+        failLifecycleStore("unsafe record");
+    }
+    const base = path.basename(file);
+    if (base.includes(path.sep) || base === "." || base === "..") {
+        failLifecycleStore("unsafe record");
+    }
+    return path.join(authority.root, base);
+};
+export const readLifecycleRecord = async (file, links = [1]) => {
+    const authority = await validateLifecycleRoot(false);
+    if (!authority)
+        return null;
+    await revalidateLifecycleRootAuthority(authority);
+    const exactFile = canonicalRecordPath(file, authority);
+    let before;
+    try {
+        before = await lstat(exactFile);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            await runTestHook("before_missing_return");
+            await revalidateLifecycleRootAuthority(authority);
+            return null;
+        }
+        failLifecycleStore("unsafe record");
+    }
+    if (!before.isFile() || before.isSymbolicLink() || before.uid !== OWNER ||
+        before.size > LIFECYCLE_RECORD_MAX_BYTES || (before.mode & 0o777) !== 0o600 ||
+        !links.includes(before.nlink)) {
+        failLifecycleStore("unsafe record");
+    }
+    await runTestHook("before_record_open");
+    await revalidateLifecycleRootAuthority(authority);
+    const handle = await open(exactFile, constants.O_RDONLY | constants.O_NOFOLLOW)
+        .catch(() => failLifecycleStore("unsafe record"));
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.uid !== OWNER || info.size > LIFECYCLE_RECORD_MAX_BYTES ||
+            (info.mode & 0o777) !== 0o600 || !links.includes(info.nlink)) {
+            failLifecycleStore("unsafe record");
+        }
+        if (before.dev !== info.dev || before.ino !== info.ino)
+            failLifecycleStore("record changed");
+        const content = await handle.readFile({ encoding: "utf8" });
+        const after = await lstat(exactFile).catch(() => failLifecycleStore("record changed"));
+        if (after.dev !== info.dev || after.ino !== info.ino)
+            failLifecycleStore("record changed");
+        await revalidateLifecycleRootAuthority(authority);
+        return content;
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+};
+export const publishLifecycleRecord = async (directory, file, content, existing = "match") => {
+    const authority = await requireLifecycleRootAuthority();
+    if (path.resolve(directory) !== authority.root)
+        failLifecycleStore("unsafe root");
+    const rootHandle = await openLifecycleAuthorityRoot(authority);
+    try {
+        if (Buffer.byteLength(content) > LIFECYCLE_RECORD_MAX_BYTES) {
+            failLifecycleStore("oversize record");
+        }
+        const final = path.join(authority.root, file);
+        if (existing === "match") {
+            if (await matchesSettledLifecyclePublication(final, content, readLifecycleRecord))
+                return false;
+        }
+        else if ((await readSettledLifecycleRecord(final, readLifecycleRecord)) !== null) {
+            return false;
+        }
+        const temp = path.join(authority.root, `.${file}.${process.pid}.${randomUUID()}.tmp`);
+        let handle;
+        let linked = false;
+        try {
+            await runTestHook("before_publish_temp_open");
+            await revalidateHeldLifecycleRoot(authority, rootHandle);
+            handle = await open(temp, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+            await handle.chmod(0o600);
+            await handle.writeFile(content, "utf8");
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            try {
+                await runTestHook("before_publish_link");
+                await revalidateHeldLifecycleRoot(authority, rootHandle);
+                await link(temp, final);
+                linked = true;
+                await syncLifecycleDirectory(authority.root);
+            }
+            catch (error) {
+                if (error.code !== "EEXIST") {
+                    failLifecycleStore("publication failed");
+                }
+            }
+        }
+        finally {
+            if (handle)
+                await handle.close().catch(() => undefined);
+            await runTestHook("before_publish_unlink");
+            await revalidateHeldLifecycleRoot(authority, rootHandle);
+            await unlink(temp).catch((error) => {
+                if (error.code !== "ENOENT")
+                    failLifecycleStore("publication cleanup failed");
+            });
+            await syncLifecycleDirectory(authority.root);
+        }
+        if (!linked && existing === "ignore") {
+            if ((await readSettledLifecycleRecord(final, readLifecycleRecord)) === null) {
+                failLifecycleStore("publication changed");
+            }
+            return false;
+        }
+        await settleLifecyclePublicationUntil(async () => {
+            const exact = await readLifecycleRecord(final, [1, 2]);
+            if (exact !== content)
+                failLifecycleStore("publication changed");
+            if ((await lstat(final).catch(() => null))?.nlink === 1) {
+                await revalidateHeldLifecycleRoot(authority, rootHandle);
+                return true;
+            }
+            return false;
+        });
+        return linked;
+    }
+    finally {
+        await rootHandle.close().catch(() => undefined);
+    }
+};

package/dist/deployment/lifecycleUpRecords.d.ts

@@ -0,0 +1,11 @@
+import { type LifecycleInvocation, type LifecycleOwnerCapability, type LifecycleUpReservation, type LifecycleUpStart } from "./lifecycleCompletionContracts.js";
+export { LIFECYCLE_UP_EXTRA_LABELS, type LifecycleUpReservation, type LifecycleUpStart, } from "./lifecycleCompletionContracts.js";
+export declare const findLifecycleUpReservation: (raw: LifecycleInvocation) => Promise<LifecycleUpReservation | null>;
+export declare const recordLifecycleUpReservation: (raw: LifecycleInvocation, reservation: Omit<LifecycleUpReservation, "invocation" | "version">, capability: LifecycleOwnerCapability) => Promise<void>;
+export interface LifecycleUpStartState {
+    readonly attempt: number;
+    readonly start: LifecycleUpStart;
+}
+export declare const findLifecycleUpStart: (raw: LifecycleInvocation) => Promise<LifecycleUpStartState | null>;
+export declare const recordLifecycleUpStart: (raw: LifecycleInvocation, start: Omit<LifecycleUpStart, "attempt" | "invocation" | "version">, capability: LifecycleOwnerCapability) => Promise<void>;
+export declare const recordLifecycleUpCleanup: (raw: LifecycleInvocation, state: LifecycleUpStartState, capability: LifecycleOwnerCapability) => Promise<void>;

package/dist/deployment/lifecycleUpRecords.js

@@ -0,0 +1,127 @@
+import path from "node:path";
+import { readSettledLifecycleRecord } from "./lifecycleCompletionPublication.js";
+import { canonicalLifecycleJson, lifecycleUpCleanupSchema, lifecycleUpReservationSchema, lifecycleUpStartSchema, LIFECYCLE_UP_CLEANUP_VERSION, LIFECYCLE_UP_RESERVATION_VERSION, LIFECYCLE_UP_START_VERSION, } from "./lifecycleCompletionContracts.js";
+import { assertLifecycleOwnerCapability } from "./lifecycleCompletionOwner.js";
+import { parseLifecycleAdmission, parseLifecycleInvocation } from "./lifecycleCompletionParsing.js";
+import { admissionPath, failLifecycleStore, lifecycleRecordName, lifecycleRoot, publishLifecycleRecord, readLifecycleRecord, recoveryPath, upCleanupPath, upReservationPath, upStartPath, } from "./lifecycleCompletionStore.js";
+export { LIFECYCLE_UP_EXTRA_LABELS, } from "./lifecycleCompletionContracts.js";
+const MAX_ATTEMPTS = 16;
+const canonical = canonicalLifecycleJson;
+const fail = failLifecycleStore;
+const exactAdmission = async (invocation) => {
+    const text = await readSettledLifecycleRecord(admissionPath(invocation.id), readLifecycleRecord);
+    if (text === null)
+        return fail("missing admission");
+    const admission = parseLifecycleAdmission(text);
+    if (canonical(admission.invocation) !== canonical(invocation))
+        fail("invocation id drift");
+    return admission;
+};
+const assertOwner = async (invocation, capability) => {
+    const recoveryText = await readSettledLifecycleRecord(recoveryPath(invocation.id), readLifecycleRecord);
+    const recovered = recoveryText ? parseLifecycleAdmission(recoveryText) : null;
+    assertLifecycleOwnerCapability(invocation, await exactAdmission(invocation), recovered, capability);
+};
+const parseRecord = (text, parse, invocation) => {
+    const value = (() => {
+        try {
+            return parse(JSON.parse(text));
+        }
+        catch {
+            return fail("invalid up lifecycle record");
+        }
+    })();
+    const record = value;
+    if (`${canonical(value)}\n` !== text || canonical(record.invocation) !== canonical(invocation)) {
+        fail("invocation id drift");
+    }
+    return value;
+};
+export const findLifecycleUpReservation = async (raw) => {
+    const invocation = parseLifecycleInvocation(raw);
+    if (invocation.operation !== "up")
+        fail("non-up reservation lookup");
+    await lifecycleRoot();
+    const text = await readSettledLifecycleRecord(upReservationPath(invocation.id), readLifecycleRecord);
+    return text === null ? null : parseRecord(text, (value) => lifecycleUpReservationSchema.parse(value), invocation);
+};
+export const recordLifecycleUpReservation = async (raw, reservation, capability) => {
+    const invocation = parseLifecycleInvocation(raw);
+    if (invocation.operation !== "up")
+        fail("non-up reservation record");
+    const directory = await lifecycleRoot();
+    await assertOwner(invocation, capability);
+    const value = lifecycleUpReservationSchema.parse({
+        ...reservation, invocation, version: LIFECYCLE_UP_RESERVATION_VERSION,
+    });
+    await publishLifecycleRecord(directory, lifecycleRecordName(invocation.id, "up-reservation"), `${canonical(value)}\n`);
+};
+const readStart = async (invocation, attempt) => {
+    const text = await readSettledLifecycleRecord(upStartPath(invocation.id, attempt), readLifecycleRecord);
+    return text === null ? null : parseRecord(text, (value) => lifecycleUpStartSchema.parse(value), invocation);
+};
+const readCleanup = async (invocation, attempt) => {
+    const text = await readSettledLifecycleRecord(upCleanupPath(invocation.id, attempt), readLifecycleRecord);
+    return text === null ? null : parseRecord(text, (value) => lifecycleUpCleanupSchema.parse(value), invocation);
+};
+const findUpAttempt = async (invocation) => {
+    for (let attempt = 0; attempt <= MAX_ATTEMPTS; attempt += 1) {
+        const start = await readStart(invocation, attempt);
+        if (start === null) {
+            if (await readCleanup(invocation, attempt))
+                fail("up cleanup without start");
+            return { active: null, next: attempt };
+        }
+        if (start.attempt !== attempt)
+            fail("up start attempt drift");
+        const cleanup = await readCleanup(invocation, attempt);
+        if (cleanup === null)
+            return { active: { attempt, start }, next: attempt };
+        if (cleanup.attempt !== attempt || cleanup.container_id !== start.container_id)
+            fail("up cleanup drift");
+    }
+    return fail("up retry limit reached");
+};
+export const findLifecycleUpStart = async (raw) => {
+    const invocation = parseLifecycleInvocation(raw);
+    if (invocation.operation !== "up")
+        fail("non-up start lookup");
+    await lifecycleRoot();
+    return (await findUpAttempt(invocation)).active;
+};
+const sameAuthority = (reservation, start) => reservation.container_name === start.container_name
+    && canonical(reservation.label_authority) === canonical(start.label_authority);
+export const recordLifecycleUpStart = async (raw, start, capability) => {
+    const invocation = parseLifecycleInvocation(raw);
+    if (invocation.operation !== "up")
+        fail("non-up start record");
+    const directory = await lifecycleRoot();
+    await assertOwner(invocation, capability);
+    const reservation = await findLifecycleUpReservation(invocation);
+    if (!reservation)
+        return fail("missing up reservation");
+    const current = await findUpAttempt(invocation);
+    const value = lifecycleUpStartSchema.parse({ ...start, attempt: current.next, invocation, version: LIFECYCLE_UP_START_VERSION });
+    if (!sameAuthority(reservation, value))
+        fail("up start authority drift");
+    if (current.active) {
+        if (canonical(current.active.start) !== canonical(value))
+            fail("active up start changed");
+        return;
+    }
+    await publishLifecycleRecord(directory, path.basename(upStartPath(invocation.id, current.next)), `${canonical(value)}\n`);
+};
+export const recordLifecycleUpCleanup = async (raw, state, capability) => {
+    const invocation = parseLifecycleInvocation(raw);
+    const directory = await lifecycleRoot();
+    await assertOwner(invocation, capability);
+    const active = await findUpAttempt(invocation);
+    if (!active.active || active.active.attempt !== state.attempt
+        || canonical(active.active.start) !== canonical(state.start))
+        fail("up cleanup without active start");
+    const value = lifecycleUpCleanupSchema.parse({
+        attempt: state.attempt, container_id: state.start.container_id, invocation,
+        version: LIFECYCLE_UP_CLEANUP_VERSION,
+    });
+    await publishLifecycleRecord(directory, path.basename(upCleanupPath(invocation.id, state.attempt)), `${canonical(value)}\n`);
+};

package/dist/deployment/native/AGENTS.md

@@ -0,0 +1,11 @@
+# Native deployment helpers
+
+This folder contains bounded, package-owned native helpers for deployment
+syscalls Node does not expose. Helpers accept validated single-component names,
+emit one bounded JSON result, and fail closed.
+
+`artifacts/` contains the verified Linux x64 and arm64 package inputs so the
+normal Node build stays offline and Docker-free. `copyArtifacts.ts` verifies
+and copies them into `dist`. Only the explicit maintainer `build:native` path
+may replace them using the digest-pinned compiler image; CI rebuilds and
+syscall-tests both architectures before publication.

package/dist/deployment/native/rename-noreplace-arm64.provenance.json

@@ -0,0 +1 @@
+{"version":"spawnfile.rename-noreplace-build.v1","architecture":"arm64","binary_sha256":"sha256:fb1f0d24fe7dfc4db18e972b9d60d839bf11ed82c78bf89cf6eca3f21502529f","builder_image":"gcc:14.2.0@sha256:b99b86a28812b1e6453a231a947dc43d76fe192788a12f344a9b568bf9f5d24c","compiler":"gcc:14.2.0","source_sha256":"sha256:64458e923931f7ca4df9ac2d19fd0361093e985ab3fbd8bf422ceb31a60b0e79","target":"linux/arm64"}

package/dist/deployment/native/rename-noreplace-x64.provenance.json

@@ -0,0 +1 @@
+{"version":"spawnfile.rename-noreplace-build.v1","architecture":"x64","binary_sha256":"sha256:5c80678b8b1325085eeb56fd8125dbad9a8e00e7a9871994702d95eabd80ab26","builder_image":"gcc:14.2.0@sha256:b99b86a28812b1e6453a231a947dc43d76fe192788a12f344a9b568bf9f5d24c","compiler":"gcc:14.2.0","source_sha256":"sha256:64458e923931f7ca4df9ac2d19fd0361093e985ab3fbd8bf422ceb31a60b0e79","target":"linux/amd64"}

package/dist/deployment/noReplaceActivation.d.ts

@@ -0,0 +1,17 @@
+type HelperResult = {
+    stderr: string;
+    stdout: string;
+};
+type HelperRun = (file: string, args: string[], options: {
+    encoding: "utf8";
+    maxBuffer: number;
+    timeout: number;
+    windowsHide: true;
+}) => Promise<HelperResult>;
+export declare const activateNoReplaceWith: (temporaryPath: string, destinationPath: string, runtime: {
+    arch: string;
+    platform: string;
+    run: HelperRun;
+}) => Promise<void>;
+export declare const activateNoReplace: (temporaryPath: string, destinationPath: string) => Promise<void>;
+export {};

package/dist/deployment/noReplaceActivation.js

@@ -0,0 +1,50 @@
+import { execFile as execFileCallback } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+const execFile = promisify(execFileCallback);
+const MAX_OUTPUT = 4096;
+const TIMEOUT_MS = 5_000;
+const component = (value) => value.length > 0 && value !== "." && value !== ".." && !value.includes(path.sep);
+export const activateNoReplaceWith = async (temporaryPath, destinationPath, runtime) => {
+    if (runtime.platform !== "linux" || (runtime.arch !== "x64" && runtime.arch !== "arm64"))
+        throw new Error("Workspace resource atomic no-replace activation is unsupported on this platform");
+    const parent = path.dirname(temporaryPath);
+    if (parent !== path.dirname(destinationPath) || !path.isAbsolute(parent))
+        throw new Error("Workspace resource activation paths must share one canonical parent");
+    const source = path.basename(temporaryPath);
+    const destination = path.basename(destinationPath);
+    if (!component(source) || !component(destination))
+        throw new Error("Workspace resource activation names must be single components");
+    const helper = fileURLToPath(new URL(`./native/rename-noreplace-${runtime.arch}`, import.meta.url));
+    try {
+        const result = await runtime.run(helper, [parent, source, destination], { encoding: "utf8", maxBuffer: MAX_OUTPUT, timeout: TIMEOUT_MS, windowsHide: true });
+        if (result.stderr !== "" || result.stdout !== '{"ok":true}\n')
+            throw new Error("Workspace resource atomic helper returned malformed output");
+    }
+    catch (error) {
+        const failure = error;
+        if (failure.killed || failure.code === "ETIMEDOUT")
+            throw new Error("Workspace resource atomic helper timed out");
+        if (failure.code === "ENOENT")
+            throw new Error("Workspace resource atomic helper is missing");
+        if (typeof failure.stdout === "string" && failure.stdout.length <= MAX_OUTPUT) {
+            try {
+                const parsed = JSON.parse(failure.stdout);
+                if (parsed.ok === false && ["EEXIST", "EXDEV", "ENOSYS", "EOPNOTSUPP"].includes(parsed.error ?? "")) {
+                    const mapped = new Error(`Workspace resource atomic activation failed: ${parsed.error}`);
+                    mapped.code = parsed.error;
+                    throw mapped;
+                }
+            }
+            catch (parsedError) {
+                if (parsedError.code)
+                    throw parsedError;
+            }
+        }
+        if (failure.message.includes("malformed output"))
+            throw failure;
+        throw new Error("Workspace resource atomic helper failed closed");
+    }
+};
+export const activateNoReplace = async (temporaryPath, destinationPath) => await activateNoReplaceWith(temporaryPath, destinationPath, { arch: process.arch, platform: process.platform, run: execFile });