superpowers-manager 0.7.3 → 0.9.0

package/dist/harnesses/pi/package.js

@@ -1,51 +1,10 @@
-import { join } from "node:path";
-import { ARTIFACT_DIGEST_RE, ARTIFACT_RECEIPT, digestArtifactTree, readArtifactObject, } from "../../artifact-tree.js";
-import { COMMIT_RE } from "../../domain/refs.js";
-import { SafetyError } from "../../safety-error.js";
-import { validateSource } from "../../selection.js";
+import { createSnapshotReceipts, } from "../../snapshot-package.js";
 import { assessPiCompatibility } from "./compatibility.js";
-import { snapshotReceiptBinding } from "../../snapshot-package.js";
-export async function readPiReceipt(root) {
-    const path = join(root, ARTIFACT_RECEIPT);
-    try {
-        const value = await readArtifactObject(root, path);
-        if (value.schema !== 1 ||
-            value.manager !== "superpowers-manager" ||
-            value.harness !== "pi" ||
-            typeof value.source !== "string" ||
-            typeof value.commit !== "string" ||
-            !COMMIT_RE.test(value.commit) ||
-            typeof value.digest !== "string" ||
-            !ARTIFACT_DIGEST_RE.test(value.digest) ||
-            typeof value.binding !== "string" ||
-            !ARTIFACT_DIGEST_RE.test(value.binding))
-            throw new Error("receipt fields");
-        validateSource(value.source);
-        if (snapshotReceiptBinding(value) !== value.binding)
-            throw new Error("receipt binding");
-        const compatibility = value.compatibility;
-        if (!compatibility ||
-            typeof compatibility !== "object" ||
-            Array.isArray(compatibility) ||
-            typeof compatibility.reason !== "string" ||
-            typeof compatibility.kind !== "string" ||
-            !["unknown", "unsupported", "supported", "experimental"].includes(compatibility.kind) ||
-            ((compatibility.kind === "supported" ||
-                compatibility.kind === "experimental") &&
-                typeof compatibility.generation !== "string"))
-            throw new Error("receipt compatibility");
-        return value;
-    }
-    catch (cause) {
-        throw new SafetyError("pi-package", `invalid Pi artifact receipt: ${path}`, { cause });
-    }
-}
-export async function readPiPackageAssessment(root) {
-    const receipt = await readPiReceipt(root);
-    if ((await digestArtifactTree(root)) !== receipt.digest)
-        throw new SafetyError("pi-package", `Pi artifact digest mismatch: ${root}`);
-    const compatibility = await assessPiCompatibility(root, {
-        effectiveSource: receipt.source,
-    });
-    return { receipt, compatibility };
-}
+const receipts = createSnapshotReceipts({
+    harness: "pi",
+    label: "Pi",
+    strictGeneration: false,
+    assessCompatibility: assessPiCompatibility,
+});
+export const readPiReceipt = receipts.readReceipt;
+export const readPiPackageAssessment = receipts.readAssessment;

package/dist/harnesses/pi/prepare.js

@@ -1,20 +1,15 @@
 import { createSnapshotPreparation } from "../../snapshot-prepare.js";
-import { piPaths } from "./paths.js";
 import { assessPiCompatibility } from "./compatibility.js";
 import { readPiPackageAssessment } from "./package.js";
-export function piPreparationLocation(ctx) {
-    return {
-        destinationRoot: piPaths(ctx.env ?? {}, process.cwd()).preparedRoot,
-        stagingLeaf: "superpowers",
-    };
-}
+import { piPaths } from "./paths.js";
 const preparation = createSnapshotPreparation({
     harness: "pi",
     label: "Pi",
-    preparationLocation: piPreparationLocation,
+    paths: piPaths,
     assessCompatibility: assessPiCompatibility,
     readAssessment: readPiPackageAssessment,
 });
+export const piPreparationLocation = preparation.preparationLocation;
 export const preparePiCandidate = preparation.prepareCandidate;
 export const inspectPiPrepared = preparation.inspectPrepared;
 export const readPiPrepared = preparation.readPrepared;

package/dist/harnesses/pi/presentation.js

@@ -1,4 +1,4 @@
-import { createSnapshotPresentation } from "../../snapshot-presentation.js";
+import { createSnapshotPresentation, probeOutput, } from "../../snapshot-presentation.js";
 const renderProbe = (facts) => {
     const fields = [
         ["harness", "pi"],
@@ -14,11 +14,6 @@ const renderProbe = (facts) => {
         ["compatibility_reason", facts.compatibility.reason],
         ["status", facts.status],
     ];
-    return {
-        human: fields
-            .map(([key, value]) => `${key.replaceAll("_", " ")}: ${value || "not present"}\n`)
-            .join(""),
-        porcelain: fields.map(([key, value]) => `${key}=${value}\n`).join(""),
-    };
+    return probeOutput(fields);
 };
 export const piPresentation = createSnapshotPresentation("Pi", renderProbe, (input) => input.receiptDigest === null && input.registrationIdentity === null);

package/dist/harnesses/pi/settings.js

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { canonicalizeProspectivePath } from "../../safe-path.js";
+import { canonicalizeProspectivePath, isErrno } from "../../safe-path.js";
 import { SafetyError } from "../../safety-error.js";
 import { parseStrictJson, } from "../../strict-json.js";
 const SETTINGS_PROFILE = {
@@ -88,12 +88,6 @@ function parsePackage(value, index, path) {
         }),
     };
 }
-function isMissing(cause) {
-    return (typeof cause === "object" &&
-        cause !== null &&
-        "code" in cause &&
-        cause.code === "ENOENT");
-}
 export function resolvePiLocalSource(source, agentDir, homeDir) {
     let normalized = source.trim();
     if (normalized.length === 0 ||
@@ -127,8 +121,9 @@ export async function readPiSettings(path, homeDir) {
         bytes = await readFile(path);
     }
     catch (cause) {
-        if (isMissing(cause))
-            return { packages: [] };
+        if (isErrno(cause, "ENOENT")) {
+            return { packages: [], managerRegistration: null };
+        }
         throw new SafetyError("pi-settings", `cannot read Pi settings ${path}`, {
             cause,
         });
@@ -166,6 +161,7 @@ export async function readPiSettings(path, homeDir) {
     }
     return {
         packages,
+        managerRegistration: managerRegistrations[0] ?? null,
         ...(settings.skills === undefined ? {} : { skills: settings.skills }),
     };
 }

package/dist/harnesses/pi/shared-skills.js

@@ -1,7 +1,12 @@
 import { readdir, readFile, readlink, realpath } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from "node:path";
 import { fileURLToPath } from "node:url";
-import { classifyPathNoFollow, isContained } from "../../safe-path.js";
+import { classifyPathNoFollow, isContained, } from "../../safe-path.js";
+// Every caller in this module treats a classification failure as its own
+// indeterminate/false outcome; null carries that failure without a try block.
+function classifyOrNull(path) {
+    return classifyPathNoFollow(path).catch(() => null);
+}
 const PI_IGNORE_FILES = [".gitignore", ".ignore", ".fdignore"];
 function toPosixPath(path) {
     return path.split(sep).join("/");
@@ -9,13 +14,9 @@ function toPosixPath(path) {
 async function ignoreControlState(directory) {
     for (const filename of PI_IGNORE_FILES) {
         const path = join(directory, filename);
-        let kind;
-        try {
-            kind = await classifyPathNoFollow(path);
-        }
-        catch {
+        const kind = await classifyOrNull(path);
+        if (kind === null)
             return "indeterminate";
-        }
         if (kind === "missing")
             continue;
         if (kind !== "regular-file")
@@ -42,13 +43,9 @@ async function collectSharedSkillDirectory(directory) {
         return { kind: "indeterminate" };
     }
     const declaredSkill = join(directory, "SKILL.md");
-    let declaredKind;
-    try {
-        declaredKind = await classifyPathNoFollow(declaredSkill);
-    }
-    catch {
+    const declaredKind = await classifyOrNull(declaredSkill);
+    if (declaredKind === null)
         return { kind: "indeterminate" };
-    }
     if (declaredKind === "regular-file") {
         return { kind: "candidates", paths: [declaredSkill] };
     }
@@ -68,13 +65,9 @@ async function collectSharedSkillDirectory(directory) {
         if (entry.name === "SKILL.md")
             return { kind: "indeterminate" };
         const path = join(directory, entry.name);
-        let kind;
-        try {
-            kind = await classifyPathNoFollow(path);
-        }
-        catch {
+        const kind = await classifyOrNull(path);
+        if (kind === null)
             return { kind: "indeterminate" };
-        }
         if (kind === "symlink" || kind === "missing") {
             return { kind: "indeterminate" };
         }
@@ -96,38 +89,26 @@ async function collectSharedPiSkills(paths) {
     const skillsRoot = join(agentsRoot, "skills");
     const sharedRoot = join(skillsRoot, "superpowers");
     for (const directory of [agentsRoot, skillsRoot]) {
-        let kind;
-        try {
-            kind = await classifyPathNoFollow(directory);
-        }
-        catch {
+        const kind = await classifyOrNull(directory);
+        if (kind === null)
             return { kind: "indeterminate" };
-        }
         if (kind === "missing")
             return { kind: "none" };
         if (kind !== "directory")
             return { kind: "indeterminate" };
     }
-    let sharedRootKind;
-    try {
-        sharedRootKind = await classifyPathNoFollow(sharedRoot);
-    }
-    catch {
+    const sharedRootKind = await classifyOrNull(sharedRoot);
+    if (sharedRootKind === null)
         return { kind: "indeterminate" };
-    }
     if (sharedRootKind === "missing")
         return { kind: "none" };
     if ((await ignoreControlState(skillsRoot)) === "indeterminate") {
         return { kind: "indeterminate" };
     }
     const discoveryRootSkill = join(skillsRoot, "SKILL.md");
-    let discoveryRootSkillKind;
-    try {
-        discoveryRootSkillKind = await classifyPathNoFollow(discoveryRootSkill);
-    }
-    catch {
+    const discoveryRootSkillKind = await classifyOrNull(discoveryRootSkill);
+    if (discoveryRootSkillKind === null)
         return { kind: "indeterminate" };
-    }
     if (discoveryRootSkillKind === "regular-file")
         return { kind: "none" };
     if (discoveryRootSkillKind !== "missing") {
@@ -248,13 +229,8 @@ async function hasSafeSharedSkillAncestors(path, sharedRoot) {
         directories.push(cursor);
     }
     for (const directory of directories) {
-        try {
-            if ((await classifyPathNoFollow(directory)) !== "directory")
-                return false;
-        }
-        catch {
+        if ((await classifyOrNull(directory)) !== "directory")
             return false;
-        }
     }
     return true;
 }
@@ -305,11 +281,8 @@ async function explicitSharedSkillActivities(settings, paths) {
             }
             continue;
         }
-        let lexicalKind;
-        try {
-            lexicalKind = await classifyPathNoFollow(path);
-        }
-        catch {
+        const lexicalKind = await classifyOrNull(path);
+        if (lexicalKind === null) {
             if (isContained(sharedRoot, path) || isContained(path, sharedRoot)) {
                 indeterminate = true;
             }
@@ -343,11 +316,8 @@ async function explicitSharedSkillActivities(settings, paths) {
             isContained(canonicalPath, canonicalSharedRoot);
         if (!related)
             continue;
-        let canonicalKind;
-        try {
-            canonicalKind = await classifyPathNoFollow(canonicalPath);
-        }
-        catch {
+        const canonicalKind = await classifyOrNull(canonicalPath);
+        if (canonicalKind === null) {
             indeterminate = true;
             continue;
         }

package/dist/harnesses/pi/state.js

@@ -6,7 +6,7 @@ import { observeSnapshot, sameSnapshotSource, } from "../../snapshot-package.js"
 import { readPiPackageAssessment, readPiReceipt, } from "./package.js";
 import { piPaths } from "./paths.js";
 import { readPiSettings, resolveCanonicalPiLocalSource, resolvePiLocalSource, } from "./settings.js";
-import { classifyPathNoFollow } from "../../safe-path.js";
+import { canonicalizeProspectivePath, classifyPathNoFollow, } from "../../safe-path.js";
 // Verified remote spellings only: Pi 0.85.1 accepts http:// as Git. Unprefixed
 // github: and git+ forms stay local; git:-wrapped aliases and explicit transports
 // normalize only an exact GitHub authority and repository path (native source
@@ -102,19 +102,12 @@ function isKnownUpstreamPiSource(raw) {
 }
 async function observeSettings(paths) {
     const settings = await readPiSettings(paths.settingsFile, paths.homeDir);
-    const installedRoot = await resolveCanonicalPiLocalSource(paths.installedRoot, paths.agentDir, paths.homeDir);
-    let registration = null;
-    for (const entry of settings.packages) {
-        if ((await resolveCanonicalPiLocalSource(entry.source, paths.agentDir, paths.homeDir)) === installedRoot) {
-            registration = entry;
-        }
-    }
-    return { settings, registration };
+    return { settings, registration: settings.managerRegistration };
 }
 async function isNamedLocalSuperpowers(entry, paths, canonicalInstalledRoot) {
     const root = resolvePiLocalSource(entry.source, paths.agentDir, paths.homeDir);
     if (root === null ||
-        (await resolveCanonicalPiLocalSource(entry.source, paths.agentDir, paths.homeDir)) === canonicalInstalledRoot)
+        (await canonicalizeProspectivePath(root)) === canonicalInstalledRoot)
         return false;
     const rootKind = await classifyPathNoFollow(root);
     if (rootKind !== "directory" && rootKind !== "symlink")

package/dist/provenance.js

@@ -1,7 +1,6 @@
 import { readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
 import { COMMIT_INPUT_RE } from "./domain/refs.js";
-import { escapePythonJsonString } from "./python-json.js";
+import { escapeNonAscii } from "./python-json-format.js";
 import { SafetyError } from "./safety-error.js";
 import { parseStrictJson, } from "./strict-json.js";
 const PROVENANCE_STRICT_PROFILE = {
@@ -57,21 +56,6 @@ export async function readGeneratedCommitLenient(path) {
         return "";
     }
 }
-// Ported from
-// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:28-31::spw_generated_metadata_path(`.
-// The path the generated tree's provenance lives at, relative to a package
-// root.
-export function generatedMetadataPath(root) {
-    return join(root, "plugins", "superpowers", ".superpowers-upstream.json");
-}
-// Ported from
-// `git show ad56569a4c161e7b122967442e2b026eeb6395f6:scripts/core/lifecycle.sh:33-37::spw_generated_commit_or_empty`.
-// Lenient by design: a missing or malformed generated provenance file yields
-// "", which the typed prepared-state flow reports as "needs prepare".
-// Aborting here would deny the operator the remediation path.
-export async function generatedCommitOrEmpty(root) {
-    return readGeneratedCommitLenient(generatedMetadataPath(root));
-}
 export async function readCodexBuildSource(path) {
     try {
         const parsed = parseStrictJson(await readFile(path), PROVENANCE_CODEX_SOURCE_PROFILE);
@@ -96,8 +80,8 @@ const PROVENANCE_KEYS = [
     "upstream_manifest_version",
 ];
 export function serializeProvenance(record) {
-    const lines = PROVENANCE_KEYS.map((key) => `  "${key}": "${escapePythonJsonString(record[key])}"`);
-    return `{\n${lines.join(",\n")}\n}\n`;
+    const ordered = Object.fromEntries(PROVENANCE_KEYS.map((key) => [key, record[key]]));
+    return `${escapeNonAscii(JSON.stringify(ordered, null, 2))}\n`;
 }
 export async function writeProvenance(path, record) {
     try {

package/dist/resource-lock.js

@@ -2,13 +2,8 @@ import { createHash, randomUUID } from "node:crypto";
 import { constants } from "node:fs";
 import { lstat, mkdir, open, readFile, realpath, rmdir, unlink, writeFile, } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { canonicalizeProspectivePath } from "./safe-path.js";
+import { canonicalizeProspectivePath, isErrno } from "./safe-path.js";
 import { SafetyError } from "./safety-error.js";
-function errnoIs(cause, code) {
-    return (cause instanceof Error &&
-        "code" in cause &&
-        cause.code === code);
-}
 async function nearestExistingDirectory(path) {
     let cursor = path;
     for (;;) {
@@ -16,7 +11,7 @@ async function nearestExistingDirectory(path) {
             return await realpath(cursor);
         }
         catch (cause) {
-            if (!errnoIs(cause, "ENOENT"))
+            if (!isErrno(cause, "ENOENT"))
                 throw cause;
             const parent = dirname(cursor);
             if (parent === cursor)
@@ -55,7 +50,7 @@ async function resourceLock(resource) {
             return { resource: canonical, lockPath: candidate };
         }
         catch (cause) {
-            if (!errnoIs(cause, "ENOENT")) {
+            if (!isErrno(cause, "ENOENT")) {
                 throw new SafetyError("resource-lock", `cannot inspect resource lock: ${canonical}`, { cause });
             }
         }
@@ -71,7 +66,7 @@ async function assertNoCompetingResourceLock(lock, held) {
             await lstat(candidate);
         }
         catch (cause) {
-            if (errnoIs(cause, "ENOENT"))
+            if (isErrno(cause, "ENOENT"))
                 continue;
             throw new SafetyError("resource-lock", `cannot inspect resource lock: ${lock.resource}`, { cause });
         }
@@ -177,12 +172,12 @@ class FilesystemResourceCoordinator {
                 }
             }
             catch (cause) {
-                if (errnoIs(cause, "ENOENT")) {
+                if (isErrno(cause, "ENOENT")) {
                     try {
                         await lstat(lock.lockPath);
                     }
                     catch (again) {
-                        if (errnoIs(again, "ENOENT"))
+                        if (isErrno(again, "ENOENT"))
                             return observation(this.#held.has(lock.lockPath) ? "uninspectable" : "idle");
                     }
                 }
@@ -206,7 +201,7 @@ class FilesystemResourceCoordinator {
                 const existing = this.#held.get(lock.lockPath);
                 if (existing !== undefined) {
                     existing.count += 1;
-                    acquired.push({ held: existing });
+                    acquired.push(existing);
                     continue;
                 }
                 const token = randomUUID();
@@ -214,7 +209,7 @@ class FilesystemResourceCoordinator {
                     await mkdir(lock.lockPath);
                 }
                 catch (cause) {
-                    if (errnoIs(cause, "EEXIST")) {
+                    if (isErrno(cause, "EEXIST")) {
                         throw new SafetyError("resource-lock", `resource is busy: ${lock.resource}`, { cause });
                     }
                     throw new SafetyError("resource-lock", `cannot acquire resource lock: ${lock.resource}`, { cause });
@@ -231,7 +226,7 @@ class FilesystemResourceCoordinator {
                     throw new SafetyError("resource-lock", `cannot record resource lock ownership: ${lock.resource}`, { cause });
                 }
                 this.#held.set(lock.lockPath, held);
-                acquired.push({ held });
+                acquired.push(held);
             }
             // A missing ancestor can appear between placement discovery and mkdir,
             // leaving concurrently acquired markers at different depths. Checking
@@ -247,9 +242,9 @@ class FilesystemResourceCoordinator {
         }
         let firstReleaseFailure = null;
         for (const entry of acquired.reverse()) {
-            const released = await releaseOwned(entry.held);
+            const released = await releaseOwned(entry);
             if (!released.keepHeld) {
-                this.#held.delete(entry.held.lockPath);
+                this.#held.delete(entry.lockPath);
             }
             firstReleaseFailure ??= released.failure;
         }

package/dist/safe-path.js

@@ -1,4 +1,4 @@
-import { lstat, readlink, realpath } from "node:fs/promises";
+import { lstat, readlink, realpath, stat } from "node:fs/promises";
 import { basename, dirname, isAbsolute, relative, resolve, sep, } from "node:path";
 import { SafetyError } from "./safety-error.js";
 export function isErrno(value, code) {
@@ -6,6 +6,33 @@ export function isErrno(value, code) {
         "code" in value &&
         value.code === code);
 }
+// Follow symlinks, like `[ -d ]` / `[ -f ]`: a regular file, a broken
+// symlink, or an unreadable path is not a directory (and vice versa), so any
+// stat failure answers false.
+export async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `ENOENT`/`ENOTDIR` mean *missing*; every other error rejects. This is the
+ * only place the absence set is defined.
+ */
+export function isAbsenceError(cause) {
+    const code = cause?.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
 export function isContained(root, candidate) {
     const suffix = relative(root, candidate);
     return (suffix === "" ||

package/dist/selection.js

@@ -1,6 +1,6 @@
 import { isIP } from "node:net";
-import { COMMIT_RE, TAG_RE, normalizeCommitInput } from "./domain/refs.js";
-import { escapePythonJsonString } from "./python-json.js";
+import { COMMIT_RE, TAG_RE } from "./domain/refs.js";
+import { escapeNonAscii } from "./python-json-format.js";
 import { SafetyError } from "./safety-error.js";
 export function selectionError(message, cause) {
     return new SafetyError("selection", message, { cause });
@@ -179,22 +179,18 @@ export function normalizeSaved(record) {
         saved_commit: record.mode === "pinned" ? record.commit : "",
     };
 }
-export function normalizePinnedArguments(arguments_) {
-    const requestedRef = normalizeCommitInput(arguments_.requestedRef) ?? arguments_.requestedRef;
-    const resolvedRef = normalizeCommitInput(arguments_.resolvedRef) ?? arguments_.resolvedRef;
-    const commit = arguments_.commit.toLowerCase();
-    return {
-        schema_version: 1,
-        mode: "pinned",
-        source: arguments_.source,
-        requested_ref: requestedRef,
-        resolved_ref: resolvedRef,
-        commit,
-    };
-}
 export function serializeRecord(record) {
-    if (record.mode === "track-latest") {
-        return `{\n  "schema_version": 1,\n  "mode": "track-latest",\n  "source": "${escapePythonJsonString(record.source)}"\n}\n`;
-    }
-    return `{\n  "schema_version": 1,\n  "mode": "pinned",\n  "source": "${escapePythonJsonString(record.source)}",\n  "requested_ref": "${escapePythonJsonString(record.requested_ref)}",\n  "resolved_ref": "${escapePythonJsonString(record.resolved_ref)}",\n  "commit": "${escapePythonJsonString(record.commit)}"\n}\n`;
+    // Keys are listed here, not taken from the caller's object, so the bytes do
+    // not depend on how the record was built.
+    const ordered = record.mode === "track-latest"
+        ? { schema_version: 1, mode: record.mode, source: record.source }
+        : {
+            schema_version: 1,
+            mode: record.mode,
+            source: record.source,
+            requested_ref: record.requested_ref,
+            resolved_ref: record.resolved_ref,
+            commit: record.commit,
+        };
+    return `${escapeNonAscii(JSON.stringify(ordered, null, 2))}\n`;
 }

package/dist/snapshot-journal.js

@@ -0,0 +1,101 @@
+import { lstat, open, readdir, readFile, rmdir, unlink, } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { atomicWriteFile } from "./atomic.js";
+import { assertNoFollowType, classifyPathNoFollow } from "./safe-path.js";
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+export async function identity(path) {
+    await assertNoFollowType(path, ["directory"]);
+    return await lstat(path);
+}
+export function journalPath(pending) {
+    return join(pending.paths.recoveryRoot, "transaction.json");
+}
+export async function requireNoRecovery(paths) {
+    await assertNoFollowType(paths.recoveryRoot, ["missing"]);
+}
+export async function hasRecovery(paths) {
+    try {
+        return (await classifyPathNoFollow(paths.recoveryRoot)) !== "missing";
+    }
+    catch {
+        return true;
+    }
+}
+async function syncDirectoryStrict(path) {
+    const directory = await open(path, "r");
+    try {
+        await directory.sync();
+    }
+    finally {
+        await directory.close();
+    }
+}
+export function publicationPaths(canonicalRoot, token) {
+    return {
+        backup: join(dirname(canonicalRoot), `.${basename(canonicalRoot)}.bak.${token}`),
+        stage: join(dirname(canonicalRoot), `.${basename(canonicalRoot)}.stage.${token}`),
+    };
+}
+// The first journal is durable before either a staging tree or backup exists.
+export async function createJournal(recoveryRoot, bytes) {
+    const path = join(recoveryRoot, "transaction.json");
+    const handle = await open(path, "wx", 0o600);
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await syncDirectoryStrict(recoveryRoot);
+    return await lstat(path);
+}
+export function createSnapshotJournal(rules) {
+    const { label } = rules;
+    async function requireIdentity(path, expected) {
+        if (!sameIdentity(await identity(path), expected))
+            throw new Error(`${label} directory changed`);
+    }
+    async function requireJournal(pending) {
+        if ((await rules.validatePaths(pending.paths)) !== pending.canonicalRoot ||
+            pending.journal.installedRoot !== pending.canonicalRoot ||
+            !/^[a-f0-9]{32}$/u.test(pending.journal.token))
+            throw new Error(`${label} recovery root changed`);
+        await requireIdentity(pending.paths.recoveryRoot, pending.recoveryIdentity);
+        const path = journalPath(pending);
+        await assertNoFollowType(path, ["regular-file"]);
+        const observed = await lstat(path);
+        if (!sameIdentity(observed, pending.journalIdentity) ||
+            observed.size > rules.readCap ||
+            !(await readFile(path)).equals(rules.serialize(pending.journal)))
+            throw new Error(`${label} recovery journal changed`);
+        const expected = publicationPaths(pending.canonicalRoot, pending.journal.token);
+        if (pending.backup !== expected.backup || pending.stage !== expected.stage)
+            throw new Error(`${label} recovery paths changed`);
+    }
+    async function phase(pending, next, changes = {}) {
+        await requireJournal(pending);
+        const journal = { ...pending.journal, ...changes, phase: next };
+        const bytes = rules.serialize(journal);
+        await atomicWriteFile(journalPath(pending), bytes, {
+            validate: async (temporary) => {
+                if (!(await readFile(temporary)).equals(bytes))
+                    throw new Error(`${label} journal write changed`);
+            },
+        });
+        await syncDirectoryStrict(pending.paths.recoveryRoot);
+        pending.journal = journal;
+        pending.journalIdentity = await lstat(journalPath(pending));
+    }
+    async function retireJournal(pending) {
+        await requireJournal(pending);
+        if ((await readdir(pending.paths.recoveryRoot)).some((name) => name !== "transaction.json"))
+            throw new Error(`unknown ${label} recovery material`);
+        await unlink(journalPath(pending));
+        await requireIdentity(pending.paths.recoveryRoot, pending.recoveryIdentity);
+        await rmdir(pending.paths.recoveryRoot);
+    }
+    return { requireIdentity, requireJournal, phase, retireJournal };
+}