spawnfile 0.1.13 → 0.1.14

package/dist/deployment/lifecycleCompletionLookup.js

@@ -0,0 +1,88 @@
+import { SpawnfileError } from "../shared/index.js";
+import { canonicalLifecycleJson, lifecycleDigest, lifecycleIdSchema, LIFECYCLE_LOOKUP_VERSION, } from "./lifecycleCompletionContracts.js";
+import { lifecycleOwnerIsAlive } from "./lifecycleCompletionOwner.js";
+import { parseLifecycleAdmission, parseLifecycleHeartbeat, parseLifecycleTerminal, } from "./lifecycleCompletionParsing.js";
+export const findLifecycleInvocationRecord = async (id, storage) => {
+    const parsed = lifecycleIdSchema.safeParse(id);
+    if (!parsed.success)
+        refuse("invalid invocation id");
+    if ((await storage.existingRoot()) === null)
+        return null;
+    const text = await storage.read(storage.admissionPath(parsed.data));
+    return text === null ? null : parseLifecycleAdmission(text).invocation;
+};
+const refuse = (message) => {
+    throw new SpawnfileError("runtime_error", `Lifecycle completion store refused: ${message}`);
+};
+export const lookupLifecycleCompletionRecord = async (id, storage) => {
+    const parsed = lifecycleIdSchema.safeParse(id);
+    if (!parsed.success)
+        refuse("invalid invocation id");
+    const value = parsed.data;
+    if ((await storage.existingRoot()) === null)
+        return {
+            invocation_id: value,
+            status: "not_applied",
+            version: LIFECYCLE_LOOKUP_VERSION,
+        };
+    const admissionText = await storage.read(storage.admissionPath(value));
+    const completionText = await storage.read(storage.completionPath(value));
+    const recoveryText = await storage.read(storage.recoveryPath(value));
+    const heartbeatText = await storage.read(storage.heartbeatPath(value));
+    if (admissionText === null &&
+        (completionText !== null || recoveryText !== null))
+        refuse("completion without admission");
+    if (admissionText === null)
+        return {
+            invocation_id: value,
+            status: "not_applied",
+            version: LIFECYCLE_LOOKUP_VERSION,
+        };
+    const admission = parseLifecycleAdmission(admissionText);
+    if (completionText !== null) {
+        const terminal = parseLifecycleTerminal(completionText);
+        if (terminal.status === "completed") {
+            if (canonicalLifecycleJson(terminal.completion.invocation) !==
+                canonicalLifecycleJson(admission.invocation))
+                refuse("completion admission drift");
+            return {
+                invocation_digest: lifecycleDigest(terminal.completion.invocation),
+                operation: terminal.completion.invocation.operation,
+                outcome_bytes: terminal.completion.outcome_bytes,
+                status: "completed",
+                version: LIFECYCLE_LOOKUP_VERSION,
+            };
+        }
+        const ambiguous = terminal.ambiguous;
+        if (ambiguous.invocation_digest !== lifecycleDigest(admission.invocation))
+            refuse("corrupt ambiguous record");
+        return {
+            invocation_digest: ambiguous.invocation_digest,
+            operation: admission.invocation.operation,
+            reason_code: ambiguous.reason_code,
+            status: "ambiguous",
+            version: LIFECYCLE_LOOKUP_VERSION,
+        };
+    }
+    if (recoveryText !== null) {
+        const recovery = parseLifecycleAdmission(recoveryText);
+        if (canonicalLifecycleJson(recovery.invocation) !==
+            canonicalLifecycleJson(admission.invocation))
+            refuse("invocation id drift");
+        if (!lifecycleOwnerIsAlive(recovery.owner, heartbeatText ? parseLifecycleHeartbeat(heartbeatText) : null)) {
+            return {
+                invocation_digest: lifecycleDigest(admission.invocation),
+                operation: admission.invocation.operation,
+                reason_code: "recovery_owner_died",
+                status: "ambiguous",
+                version: LIFECYCLE_LOOKUP_VERSION,
+            };
+        }
+    }
+    return {
+        invocation_digest: lifecycleDigest(admission.invocation),
+        operation: admission.invocation.operation,
+        status: "pending",
+        version: LIFECYCLE_LOOKUP_VERSION,
+    };
+};

package/dist/deployment/lifecycleCompletionOwner.d.ts

@@ -0,0 +1,8 @@
+import { type LifecycleAdmission, type LifecycleInvocation, type LifecycleOwnerCapability } from "./lifecycleCompletionContracts.js";
+export declare const LIFECYCLE_LEASE_MS = 30000;
+export declare const createLifecycleAdmission: (invocation: LifecycleInvocation) => LifecycleAdmission;
+export declare const lifecycleOwnerIsAlive: (owner: LifecycleAdmission["owner"], heartbeat?: {
+    epoch: string;
+    lease_expires_at: number;
+} | null) => boolean;
+export declare const assertLifecycleOwnerCapability: (invocation: LifecycleInvocation, admitted: LifecycleAdmission, recovered: LifecycleAdmission | null, capability: LifecycleOwnerCapability) => void;

package/dist/deployment/lifecycleCompletionOwner.js

@@ -0,0 +1,31 @@
+import { randomUUID } from "node:crypto";
+import { LIFECYCLE_ADMISSION_VERSION, LIFECYCLE_OWNER_VERSION, canonicalLifecycleJson, } from "./lifecycleCompletionContracts.js";
+import { SpawnfileError } from "../shared/index.js";
+export const LIFECYCLE_LEASE_MS = 30_000;
+export const createLifecycleAdmission = (invocation) => ({
+    invocation,
+    owner: {
+        epoch: randomUUID(),
+        lease_expires_at: Date.now() + LIFECYCLE_LEASE_MS,
+        pid: process.pid,
+        version: LIFECYCLE_OWNER_VERSION,
+    },
+    version: LIFECYCLE_ADMISSION_VERSION,
+});
+export const lifecycleOwnerIsAlive = (owner, heartbeat) => {
+    const expiry = heartbeat?.epoch === owner.epoch
+        ? heartbeat.lease_expires_at
+        : owner.lease_expires_at;
+    return expiry > Date.now();
+};
+export const assertLifecycleOwnerCapability = (invocation, admitted, recovered, capability) => {
+    if (recovered &&
+        canonicalLifecycleJson(recovered.invocation) !==
+            canonicalLifecycleJson(invocation))
+        throw new SpawnfileError("runtime_error", "Lifecycle invocation id drift");
+    const active = recovered
+        ? { epoch: recovered.owner.epoch, role: "recovery" }
+        : { epoch: admitted.owner.epoch, role: "initial" };
+    if (capability?.epoch !== active.epoch || capability?.role !== active.role)
+        throw new SpawnfileError("runtime_error", "Lifecycle completion store refused: invalid owner capability");
+};

package/dist/deployment/lifecycleCompletionParsing.d.ts

@@ -0,0 +1,12 @@
+import { type LifecycleCompletion, type LifecycleAdmission, type LifecycleAmbiguousReason, type LifecycleTerminal, type LifecycleInvocation, type LifecycleHeartbeat } from "./lifecycleCompletionContracts.js";
+export declare const parseLifecycleInvocation: (raw: unknown) => LifecycleInvocation;
+export declare const parseLifecycleHeartbeat: (text: string) => LifecycleHeartbeat;
+export declare const parseLifecycleAdmission: (text: string) => LifecycleAdmission;
+export declare const parseLifecycleCompletion: (text: string) => LifecycleCompletion;
+export declare const parseLifecycleAmbiguous: (text: string) => {
+    invocation_digest: string;
+    reason_code: LifecycleAmbiguousReason;
+    version: "spawnfile.lifecycle-ambiguous.v1";
+};
+export declare const parseLifecycleTerminal: (text: string) => LifecycleTerminal;
+export declare const parseLifecycleCompletedTerminal: (text: string) => LifecycleCompletion;

package/dist/deployment/lifecycleCompletionParsing.js

@@ -0,0 +1,108 @@
+import { SpawnfileError } from "../shared/index.js";
+import { parseExportIndex } from "./artifactsExportTypes.js";
+import { parseDownReceipt } from "./downReceiptTypes.js";
+import { canonicalLifecycleJson, lifecycleAdmissionSchema, lifecycleAmbiguousSchema, lifecycleCompletionSchema, lifecycleExportOutcomeSchema, lifecycleHeartbeatSchema, lifecycleInvocationSchema, lifecycleTerminalSchema, } from "./lifecycleCompletionContracts.js";
+import { parseUpReceipt } from "./upReceiptTypes.js";
+const refuse = (message) => {
+    throw new SpawnfileError("runtime_error", `Lifecycle completion store refused: ${message}`);
+};
+export const parseLifecycleInvocation = (raw) => {
+    const parsed = lifecycleInvocationSchema.safeParse(raw);
+    if (!parsed.success)
+        refuse("invalid invocation contract");
+    return parsed.data;
+};
+export const parseLifecycleHeartbeat = (text) => {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        refuse("corrupt heartbeat");
+    }
+    const parsed = lifecycleHeartbeatSchema.safeParse(raw);
+    if (!parsed.success || `${canonicalLifecycleJson(parsed.data)}\n` !== text)
+        refuse("corrupt heartbeat");
+    return parsed.data;
+};
+export const parseLifecycleAdmission = (text) => {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        refuse("corrupt admission");
+    }
+    const parsed = lifecycleAdmissionSchema.safeParse(raw);
+    if (!parsed.success || `${canonicalLifecycleJson(parsed.data)}\n` !== text)
+        refuse("noncanonical admission");
+    return parsed.data;
+};
+export const parseLifecycleCompletion = (text) => {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        refuse("corrupt completion");
+    }
+    const parsed = lifecycleCompletionSchema.safeParse(raw);
+    if (!parsed.success || `${canonicalLifecycleJson(parsed.data)}\n` !== text)
+        refuse("corrupt completion");
+    const value = parsed.data;
+    let outcome;
+    try {
+        outcome = JSON.parse(value.outcome_bytes);
+    }
+    catch {
+        refuse("corrupt outcome");
+    }
+    if (JSON.stringify(outcome, null, 2) !== value.outcome_bytes)
+        refuse("noncanonical outcome");
+    try {
+        if (value.invocation.operation === "up")
+            parseUpReceipt(outcome);
+        else if (value.invocation.operation === "down")
+            parseDownReceipt(outcome);
+        else
+            parseExportIndex(lifecycleExportOutcomeSchema.parse(outcome).index);
+    }
+    catch {
+        refuse("outcome operation mismatch");
+    }
+    return value;
+};
+export const parseLifecycleAmbiguous = (text) => {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        refuse("corrupt ambiguous record");
+    }
+    const parsed = lifecycleAmbiguousSchema.safeParse(raw);
+    if (!parsed.success || `${canonicalLifecycleJson(parsed.data)}\n` !== text)
+        refuse("corrupt ambiguous record");
+    return parsed.data;
+};
+export const parseLifecycleTerminal = (text) => {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        refuse("corrupt terminal record");
+    }
+    const parsed = lifecycleTerminalSchema.safeParse(raw);
+    if (!parsed.success || `${canonicalLifecycleJson(parsed.data)}\n` !== text)
+        refuse("corrupt terminal record");
+    if (parsed.data.status === "completed")
+        parseLifecycleCompletion(`${canonicalLifecycleJson(parsed.data.completion)}\n`);
+    return parsed.data;
+};
+export const parseLifecycleCompletedTerminal = (text) => {
+    const terminal = parseLifecycleTerminal(text);
+    if (terminal.status !== "completed")
+        refuse("ambiguous terminal");
+    return terminal.completion;
+};

package/dist/deployment/lifecycleCompletionPaths.d.ts

@@ -0,0 +1,9 @@
+export declare const failLifecycleStore: (message: string) => never;
+export declare const resolveLifecycleCompletionDirectory: () => string;
+export declare const lifecycleRecordName: (id: string, kind: "admission" | "completion" | "evidence" | "plan" | "recovery") => string;
+export declare const resolveLifecycleCompletionPath: (id: string) => string;
+export declare const admissionPath: (id: string) => string;
+export declare const planPath: (id: string) => string;
+export declare const recoveryPath: (id: string) => string;
+export declare const evidencePath: (id: string) => string;
+export declare const heartbeatPath: (id: string) => string;

package/dist/deployment/lifecycleCompletionPaths.js

@@ -0,0 +1,16 @@
+import path from "node:path";
+import { resolveSpawnfileHome } from "../auth/index.js";
+import { SpawnfileError } from "../shared/index.js";
+import { lifecycleIdSchema } from "./lifecycleCompletionContracts.js";
+export const failLifecycleStore = (message) => {
+    throw new SpawnfileError("runtime_error", `Lifecycle completion store refused: ${message}`);
+};
+export const resolveLifecycleCompletionDirectory = () => path.join(resolveSpawnfileHome(), "lifecycle-completions");
+export const lifecycleRecordName = (id, kind) => `${lifecycleIdSchema.parse(id)}.${kind}`;
+const lifecyclePath = (id, kind) => path.join(resolveLifecycleCompletionDirectory(), lifecycleRecordName(id, kind));
+export const resolveLifecycleCompletionPath = (id) => lifecyclePath(id, "completion");
+export const admissionPath = (id) => lifecyclePath(id, "admission");
+export const planPath = (id) => lifecyclePath(id, "plan");
+export const recoveryPath = (id) => lifecyclePath(id, "recovery");
+export const evidencePath = (id) => lifecyclePath(id, "evidence");
+export const heartbeatPath = (id) => path.join(resolveLifecycleCompletionDirectory(), `${lifecycleIdSchema.parse(id)}.heartbeat`);

package/dist/deployment/lifecycleCompletionPublication.d.ts

@@ -0,0 +1,5 @@
+type RecordReader = (file: string, links?: readonly number[]) => Promise<string | null>;
+export declare const settleLifecyclePublication: (file: string) => Promise<void>;
+export declare const readSettledLifecycleRecord: (file: string, read: RecordReader) => Promise<string | null>;
+export declare const matchesSettledLifecyclePublication: (file: string, expected: string, read: RecordReader) => Promise<boolean>;
+export {};

package/dist/deployment/lifecycleCompletionPublication.js

@@ -0,0 +1,35 @@
+import { lstat } from "node:fs/promises";
+import { SpawnfileError } from "../shared/index.js";
+const refuse = (message) => {
+    throw new SpawnfileError("runtime_error", `Lifecycle completion store refused: ${message}`);
+};
+export const settleLifecyclePublication = async (file) => {
+    for (let attempt = 0; attempt < 16; attempt += 1) {
+        const info = await lstat(file).catch(() => refuse("publication changed"));
+        if (info.nlink === 1)
+            return;
+        await new Promise((resolve) => setImmediate(resolve));
+    }
+    refuse("publication did not settle");
+};
+export const readSettledLifecycleRecord = async (file, read) => {
+    const text = await read(file, [1, 2]);
+    if (text === null)
+        return null;
+    const info = await lstat(file).catch(() => refuse("publication changed"));
+    if (info.nlink === 2) {
+        await settleLifecyclePublication(file);
+        return read(file);
+    }
+    if (info.nlink !== 1)
+        refuse("unsafe record");
+    return text;
+};
+export const matchesSettledLifecyclePublication = async (file, expected, read) => {
+    const prior = await readSettledLifecycleRecord(file, read);
+    if (prior === null)
+        return false;
+    if (prior !== expected)
+        refuse("divergent immutable record");
+    return true;
+};

package/dist/deployment/lifecycleCompletionRecovery.d.ts

@@ -0,0 +1,21 @@
+import { type LifecycleAdmission, type LifecycleAmbiguousReason, type LifecycleCompletion, type LifecycleInvocation, type LifecycleOwnerCapability } from "./lifecycleCompletionContracts.js";
+interface RecoveryStorage {
+    exactAdmission: (invocation: LifecycleInvocation) => Promise<LifecycleAdmission | null>;
+    exactCompletion: (invocation: LifecycleInvocation) => Promise<LifecycleCompletion | null>;
+    publish: (invocation: LifecycleInvocation, kind: "completion" | "recovery", content: string) => Promise<boolean>;
+    readRecovery: (invocation: LifecycleInvocation) => Promise<string | null>;
+    readHeartbeat: (invocation: LifecycleInvocation) => Promise<{
+        epoch: string;
+        lease_expires_at: number;
+    } | null>;
+}
+export type LifecycleRecoveryClaim = {
+    capability: LifecycleOwnerCapability;
+    status: "owner";
+} | {
+    status: "ambiguous" | "pending" | "replay";
+};
+export declare const materializeDeadRecoveryAmbiguous: (invocation: LifecycleInvocation, publish: RecoveryStorage["publish"]) => Promise<void>;
+export declare const claimLifecycleRecoveryRecord: (invocation: LifecycleInvocation, storage: RecoveryStorage) => Promise<LifecycleRecoveryClaim>;
+export declare const markLifecycleAmbiguousRecord: (invocation: LifecycleInvocation, reasonCode: LifecycleAmbiguousReason, capability: LifecycleOwnerCapability, storage: RecoveryStorage) => Promise<void>;
+export {};

package/dist/deployment/lifecycleCompletionRecovery.js

@@ -0,0 +1,56 @@
+import { canonicalLifecycleJson, lifecycleAmbiguousSchema, lifecycleDigest, LIFECYCLE_TERMINAL_VERSION, } from "./lifecycleCompletionContracts.js";
+import { assertLifecycleOwnerCapability, createLifecycleAdmission, lifecycleOwnerIsAlive, } from "./lifecycleCompletionOwner.js";
+import { parseLifecycleAdmission } from "./lifecycleCompletionParsing.js";
+const ambiguousTerminal = (invocation, reasonCode) => {
+    const ambiguous = lifecycleAmbiguousSchema.parse({
+        invocation_digest: lifecycleDigest(invocation),
+        reason_code: reasonCode,
+        version: "spawnfile.lifecycle-ambiguous.v1",
+    });
+    return `${canonicalLifecycleJson({
+        ambiguous,
+        status: "ambiguous",
+        version: LIFECYCLE_TERMINAL_VERSION,
+    })}\n`;
+};
+export const materializeDeadRecoveryAmbiguous = async (invocation, publish) => {
+    await publish(invocation, "completion", ambiguousTerminal(invocation, "recovery_owner_died"));
+};
+export const claimLifecycleRecoveryRecord = async (invocation, storage) => {
+    const stored = await storage.exactAdmission(invocation);
+    const completion = await storage.exactCompletion(invocation);
+    if (!stored)
+        throw new Error("missing admission");
+    if (completion)
+        return { status: "replay" };
+    if (lifecycleOwnerIsAlive(stored.owner, await storage.readHeartbeat(invocation)))
+        return { status: "pending" };
+    const recovery = createLifecycleAdmission(invocation);
+    if (await storage.publish(invocation, "recovery", `${canonicalLifecycleJson(recovery)}\n`))
+        return {
+            capability: { epoch: recovery.owner.epoch, role: "recovery" },
+            status: "owner",
+        };
+    const text = await storage.readRecovery(invocation);
+    if (text === null)
+        throw new Error("missing recovery owner");
+    const prior = parseLifecycleAdmission(text);
+    if (canonicalLifecycleJson(prior.invocation) !==
+        canonicalLifecycleJson(invocation))
+        throw new Error("invocation id drift");
+    if (lifecycleOwnerIsAlive(prior.owner, await storage.readHeartbeat(invocation)))
+        return { status: "pending" };
+    await materializeDeadRecoveryAmbiguous(invocation, storage.publish);
+    return { status: "ambiguous" };
+};
+export const markLifecycleAmbiguousRecord = async (invocation, reasonCode, capability, storage) => {
+    const admitted = await storage.exactAdmission(invocation);
+    if (!admitted)
+        throw new Error("missing admission");
+    const recoveryText = await storage.readRecovery(invocation);
+    const recovered = recoveryText ? parseLifecycleAdmission(recoveryText) : null;
+    assertLifecycleOwnerCapability(invocation, admitted, recovered, capability);
+    if (capability.role !== "recovery")
+        throw new Error("invalid owner capability");
+    await storage.publish(invocation, "completion", ambiguousTerminal(invocation, reasonCode));
+};

package/dist/deployment/lifecycleCompletionRoot.d.ts

@@ -0,0 +1,21 @@
+import { open } from "node:fs/promises";
+interface PathIdentity {
+    readonly dev: number;
+    readonly ino: number;
+    readonly path: string;
+}
+export interface LifecycleRootAuthority {
+    readonly canonicalHome: string;
+    readonly configuredHome: string;
+    readonly identities: readonly PathIdentity[];
+    readonly root: string;
+}
+export declare const revalidateLifecycleRootAuthority: (authority: LifecycleRootAuthority) => Promise<void>;
+export declare const validateLifecycleRoot: (create: boolean) => Promise<LifecycleRootAuthority | null>;
+export declare const lifecycleRoot: () => Promise<string>;
+export declare const existingLifecycleRoot: () => Promise<string | null>;
+export declare const requireLifecycleRootAuthority: () => Promise<LifecycleRootAuthority>;
+export declare const openLifecycleAuthorityRoot: (authority: LifecycleRootAuthority) => Promise<import("fs/promises").FileHandle>;
+export declare const revalidateHeldLifecycleRoot: (authority: LifecycleRootAuthority, handle: Awaited<ReturnType<typeof open>>) => Promise<void>;
+export declare const syncLifecycleDirectory: (directory: string) => Promise<void>;
+export {};

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);
+};