@agent-teams/engineering-foundation 0.16.1 → 0.17.0-rc.1

package/dist/repository-mutation/adapters/node/node-known-file-transaction-filesystem.js

@@ -0,0 +1,129 @@
+import { createHash } from "node:crypto";
+import { lstat, readdir, realpath } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { portableRepositoryPathIdentity, portableRepositoryPathProblem } from "../../application/model/repository-path.js";
+import { captureFileHandleIdentity, readBoundedRegularFile } from "./node-bounded-regular-file.js";
+import { isLexicallyContainedPath } from "./node-repository-path.js";
+const MAXIMUM_MANAGED_FILE_BYTES = 8 * 1024 * 1024;
+export class KnownFileTransactionError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "KnownFileTransactionError";
+        this.code = code;
+    }
+}
+export function knownFileErrorCode(error) {
+    return error instanceof Error && "code" in error
+        ? error.code
+        : undefined;
+}
+export function sameKnownFileIdentity(left, right) {
+    return left.birthtimeNs === right.birthtimeNs &&
+        left.dev === right.dev && left.ino === right.ino;
+}
+export function knownFileImageBytes(image) {
+    return Buffer.from(image.contentBase64, "base64");
+}
+export function matchesKnownFileImage(observed, image) {
+    return observed.state === "file" && observed.bytes !== undefined &&
+        observed.bytes.byteLength === image.size &&
+        `sha256:${createHash("sha256").update(observed.bytes).digest("hex")}` === image.digest &&
+        observed.mode === image.mode;
+}
+export function knownFileTemporaryName(path, planDigest, operationIndex) {
+    return `.${basename(path)}.agent-teams.${planDigest.slice(7, 23)}.${operationIndex}.tmp`;
+}
+export function knownFileCaptureDirectoryName(path, planDigest, operationIndex) {
+    return `.${basename(path)}.agent-teams.capture.${planDigest.slice(7, 23)}.${operationIndex}`;
+}
+export async function canonicalKnownFileRoot(consumerRoot) {
+    const requested = resolve(consumerRoot);
+    const metadata = await lstat(requested);
+    if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+        throw new KnownFileTransactionError("KNOWN_FILE_ROOT_INVALID", "Consumer root must be one real directory, not a symlink.");
+    }
+    return realpath(requested);
+}
+export async function knownFileAliasEntry(parent, requested) {
+    const identity = portableRepositoryPathIdentity(requested);
+    const matches = (await readdir(parent)).filter((entry) => portableRepositoryPathIdentity(entry) === identity);
+    if (matches.some((entry) => entry !== requested)) {
+        throw new KnownFileTransactionError("KNOWN_FILE_PATH_ALIAS", `Portable case or Unicode path collision blocks ${requested}.`);
+    }
+    return matches.find((entry) => entry === requested);
+}
+async function resolveExistingParent(root, repositoryPath) {
+    const problem = portableRepositoryPathProblem(repositoryPath);
+    if (problem !== undefined) {
+        throw new KnownFileTransactionError("KNOWN_FILE_PATH_INVALID", `Repository path is not portable (${problem}): ${repositoryPath}.`);
+    }
+    const segments = repositoryPath.split("/");
+    segments.pop();
+    let current = root;
+    for (const segment of segments) {
+        if (await knownFileAliasEntry(current, segment) === undefined) {
+            return { absolute: current, complete: false };
+        }
+        current = join(current, segment);
+        const metadata = await lstat(current);
+        if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+            throw new KnownFileTransactionError("KNOWN_FILE_ANCESTOR_INVALID", `Repository ancestor must be one real directory: ${repositoryPath}.`);
+        }
+        const canonical = await realpath(current);
+        if (!isLexicallyContainedPath(root, canonical) || canonical !== current) {
+            throw new KnownFileTransactionError("KNOWN_FILE_PATH_ESCAPE", `Repository ancestor escapes or aliases the root: ${repositoryPath}.`);
+        }
+    }
+    return { absolute: current, complete: true };
+}
+export async function observeKnownFile(root, repositoryPath, maximumBytes) {
+    const parent = await resolveExistingParent(root, repositoryPath);
+    if (!parent.complete) {
+        return { state: "absent" };
+    }
+    const name = repositoryPath.split("/").at(-1);
+    if (await knownFileAliasEntry(parent.absolute, name) === undefined) {
+        return { state: "absent" };
+    }
+    const path = join(root, ...repositoryPath.split("/"));
+    const metadata = await lstat(path, { bigint: true });
+    if (metadata.isSymbolicLink() || !metadata.isFile()) {
+        throw new KnownFileTransactionError("KNOWN_FILE_DESTINATION_INVALID", `Managed path must be a real regular file: ${repositoryPath}.`);
+    }
+    const observed = await readBoundedRegularFile(path, Math.max(maximumBytes, MAXIMUM_MANAGED_FILE_BYTES));
+    if (observed.outcome !== "read") {
+        throw new KnownFileTransactionError("KNOWN_FILE_UNSTABLE", `Managed path is oversized, unstable, or invalid: ${repositoryPath}.`);
+    }
+    if (observed.linkCount !== 1n) {
+        throw new KnownFileTransactionError("KNOWN_FILE_HARDLINK", `Managed path has multiple hard links: ${repositoryPath}.`);
+    }
+    return {
+        state: "file",
+        bytes: observed.bytes,
+        identity: observed.identity,
+        mode: observed.mode & 0o777
+    };
+}
+export function maximumKnownFileEvidenceBytes(operation) {
+    return Math.max(operation.postimage.size, ...(operation.precondition.state === "known-file"
+        ? operation.precondition.acceptedPreimages.map(({ size }) => size)
+        : [0]));
+}
+export function classifyKnownFileOperation(operation, observed) {
+    if (matchesKnownFileImage(observed, operation.postimage)) {
+        return { path: operation.path, state: "already-satisfied" };
+    }
+    if (operation.precondition.state === "absent") {
+        if (observed.state !== "absent") {
+            throw new KnownFileTransactionError("KNOWN_FILE_CAS_MISMATCH", `Expected an absent managed path: ${operation.path}.`);
+        }
+        return { path: operation.path, state: "pending" };
+    }
+    const matchedPreimage = operation.precondition.acceptedPreimages.findIndex((image) => matchesKnownFileImage(observed, image));
+    if (matchedPreimage === -1) {
+        throw new KnownFileTransactionError("KNOWN_FILE_CAS_MISMATCH", `Managed path does not match an exact accepted preimage: ${operation.path}.`);
+    }
+    return { path: operation.path, state: "pending", matchedPreimage };
+}
+//# sourceMappingURL=node-known-file-transaction-filesystem.js.map

package/dist/repository-mutation/adapters/node/node-known-file-transaction-filesystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-known-file-transaction-filesystem.js","sourceRoot":"","sources":["../../../../src/repository-mutation/adapters/node/node-known-file-transaction-filesystem.ts"],"names":[],"mappings":"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"}

package/dist/repository-mutation/adapters/node/node-known-file-transaction-inspection.d.ts

@@ -0,0 +1,12 @@
+export type KnownFileTransactionBarrierInspection = {
+    readonly state: "idle";
+} | {
+    readonly state: "recovery-required";
+    readonly code: "KNOWN_FILE_OPERATION_ACTIVE" | "KNOWN_FILE_RECOVERY_REQUIRED";
+    readonly recoverableByInstalledBuild: boolean;
+    readonly message: string;
+};
+export declare function inspectKnownFileTransactionBarrier(options: {
+    readonly consumerRoot: string;
+}): Promise<KnownFileTransactionBarrierInspection>;
+//# sourceMappingURL=node-known-file-transaction-inspection.d.ts.map

package/dist/repository-mutation/adapters/node/node-known-file-transaction-inspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-known-file-transaction-inspection.d.ts","sourceRoot":"","sources":["../../../../src/repository-mutation/adapters/node/node-known-file-transaction-inspection.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,qCAAqC,GAC7C;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC1B;IACE,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,QAAQ,CAAC,IAAI,EACT,6BAA6B,GAC7B,8BAA8B,CAAC;IACnC,QAAQ,CAAC,2BAA2B,EAAE,OAAO,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAYN,wBAAsB,kCAAkC,CAAC,OAAO,EAAE;IAChE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,GAAG,OAAO,CAAC,qCAAqC,CAAC,CA6BjD"}

package/dist/repository-mutation/adapters/node/node-known-file-transaction-inspection.js

@@ -0,0 +1,46 @@
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+import { LOCAL_OPERATION_LOCK, LOCAL_STATE_DIRECTORY } from "../../../foundation-state-contract.js";
+import { createNodeFoundationTransactionCoordinator } from "../../../transaction-coordination/adapters/node/node-foundation-transaction-coordinator.js";
+import { canonicalKnownFileRoot, knownFileErrorCode } from "./node-known-file-transaction-filesystem.js";
+async function operationLockExists(root) {
+    try {
+        await lstat(join(root, LOCAL_STATE_DIRECTORY, LOCAL_OPERATION_LOCK));
+        return true;
+    }
+    catch (error) {
+        if (knownFileErrorCode(error) === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function inspectKnownFileTransactionBarrier(options) {
+    const root = await canonicalKnownFileRoot(options.consumerRoot);
+    const [hasOperationLock, status] = await Promise.all([
+        operationLockExists(root),
+        createNodeFoundationTransactionCoordinator(root).then((coordinator) => coordinator.inspect())
+    ]);
+    if (status.state !== "idle") {
+        const recoverableByInstalledBuild = status.state === "pending" &&
+            status.operationKind === "known-file-transaction" &&
+            !status.diagnostics.some(({ code }) => code === "FOUNDATION_TRANSACTION_VERSION_MISMATCH");
+        return Object.freeze({
+            state: "recovery-required",
+            code: "KNOWN_FILE_RECOVERY_REQUIRED",
+            recoverableByInstalledBuild,
+            message: status.diagnostics[0]?.message ??
+                "Foundation transaction evidence must be recovered before consumer integration can continue."
+        });
+    }
+    if (hasOperationLock) {
+        return Object.freeze({
+            state: "recovery-required",
+            code: "KNOWN_FILE_OPERATION_ACTIVE",
+            recoverableByInstalledBuild: false,
+            message: "A Foundation operation is active or interrupted; retry after it completes or recover its evidence."
+        });
+    }
+    return Object.freeze({ state: "idle" });
+}
+//# sourceMappingURL=node-known-file-transaction-inspection.js.map

package/dist/repository-mutation/adapters/node/node-known-file-transaction-inspection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-known-file-transaction-inspection.js","sourceRoot":"","sources":["../../../../src/repository-mutation/adapters/node/node-known-file-transaction-inspection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,0CAA0C,EAAE,MAAM,4FAA4F,CAAC;AACxJ,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,6CAA6C,CAAC;AAazG,KAAK,UAAU,mBAAmB,CAAC,IAAY;IAC7C,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,qBAAqB,EAAE,oBAAoB,CAAC,CAAC,CAAC;QACrE,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,kBAAkB,CAAC,KAAK,CAAC,KAAK,QAAQ,EAAE,CAAC;YAAA,OAAO,KAAK,CAAC;QAAA,CAAC;QAC3D,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kCAAkC,CAAC,OAExD;IACC,MAAM,IAAI,GAAG,MAAM,sBAAsB,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;IAChE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACnD,mBAAmB,CAAC,IAAI,CAAC;QACzB,0CAA0C,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;KAC9F,CAAC,CAAC;IACH,IAAI,MAAM,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;QAC5B,MAAM,2BAA2B,GAAG,MAAM,CAAC,KAAK,KAAK,SAAS;YAC5D,MAAM,CAAC,aAAa,KAAK,wBAAwB;YACjD,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CACpC,IAAI,KAAK,yCAAyC,CACnD,CAAC;QACJ,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,KAAK,EAAE,mBAAmB;YAC1B,IAAI,EAAE,8BAA8B;YACpC,2BAA2B;YAC3B,OAAO,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,OAAO;gBACrC,6FAA6F;SAChG,CAAC,CAAC;IACL,CAAC;IACD,IAAI,gBAAgB,EAAE,CAAC;QACrB,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,KAAK,EAAE,mBAAmB;YAC1B,IAAI,EAAE,6BAA6B;YACnC,2BAA2B,EAAE,KAAK;YAClC,OAAO,EAAE,oGAAoG;SAC9G,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;AAC1C,CAAC"}

package/dist/repository-mutation/adapters/node/node-known-file-transaction-journal-store.d.ts

@@ -0,0 +1,21 @@
+import type { KnownFileTransactionEnvelopeV1 } from "../../application/model/known-file-transaction-journal.js";
+import { captureFileHandleIdentity } from "./node-bounded-regular-file.js";
+export interface KnownFileJournalAuthority {
+    readonly digest: `sha256:${string}`;
+    readonly identity: Awaited<ReturnType<typeof captureFileHandleIdentity>>;
+}
+declare function readEnvelope(path: string): Promise<{
+    readonly authority: KnownFileJournalAuthority;
+    readonly envelope: KnownFileTransactionEnvelopeV1;
+} | undefined>;
+export declare class NodeKnownFileTransactionJournalStore {
+    #private;
+    constructor(stateDirectory: string);
+    read(): Promise<Awaited<ReturnType<typeof readEnvelope>>>;
+    create(envelope: KnownFileTransactionEnvelopeV1): Promise<KnownFileJournalAuthority>;
+    replace(expected: KnownFileJournalAuthority, envelope: KnownFileTransactionEnvelopeV1): Promise<KnownFileJournalAuthority>;
+    remove(expected: KnownFileJournalAuthority): Promise<void>;
+    canonicalizeTemporary(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=node-known-file-transaction-journal-store.d.ts.map

package/dist/repository-mutation/adapters/node/node-known-file-transaction-journal-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-known-file-transaction-journal-store.d.ts","sourceRoot":"","sources":["../../../../src/repository-mutation/adapters/node/node-known-file-transaction-journal-store.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,2DAA2D,CAAC;AAEhH,OAAO,EACL,yBAAyB,EAG1B,MAAM,gCAAgC,CAAC;AAOxC,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,UAAU,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,yBAAyB,CAAC,CAAC,CAAC;CAC1E;AAwBD,iBAAe,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACjD,QAAQ,CAAC,SAAS,EAAE,yBAAyB,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,8BAA8B,CAAC;CACnD,GAAG,SAAS,CAAC,CAsBb;AAUD,qBAAa,oCAAoC;;IAK/C,YAAmB,cAAc,EAAE,MAAM,EAIxC;IAEY,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAMrE;IA8BY,MAAM,CAAC,QAAQ,EAAE,8BAA8B,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAUhG;IAEY,OAAO,CAClB,QAAQ,EAAE,yBAAyB,EACnC,QAAQ,EAAE,8BAA8B,GACvC,OAAO,CAAC,yBAAyB,CAAC,CASpC;IAEY,MAAM,CAAC,QAAQ,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAItE;IAEY,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CA2ClD;CACF"}

package/dist/repository-mutation/adapters/node/node-known-file-transaction-journal-store.js

@@ -0,0 +1,178 @@
+import { createHash } from "node:crypto";
+import { open, rename, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { TextDecoder } from "node:util";
+import { canonicalJson } from "../../../canonical-json.js";
+import { FOUNDATION_TRANSACTION_FILE, KNOWN_FILE_TRANSACTION_TEMPORARY_FILE } from "../../../foundation-state-contract.js";
+import { parseStrictJson } from "../../../strict-json.js";
+import { assertKnownFileTransactionEnvelope } from "../../application/policies/known-file-transaction-envelope.js";
+import { captureFileHandleIdentity, pathMatchesRegularFileIdentity, readBoundedRegularFile } from "./node-bounded-regular-file.js";
+import { cleanupIdentityMatchingOwnedTemporary } from "./node-cleanup-owned-temporary.js";
+import { syncDirectoryDurably, syncDirectoryStrictly } from "./node-directory-durability.js";
+const MAXIMUM_JOURNAL_BYTES = 32 * 1024 * 1024;
+const strictUtf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+function errorCode(error) {
+    return error instanceof Error && "code" in error
+        ? error.code
+        : undefined;
+}
+function digest(content) {
+    return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+function bytes(envelope) {
+    assertKnownFileTransactionEnvelope(envelope);
+    const result = Buffer.from(`${canonicalJson(envelope)}\n`, "utf8");
+    if (result.byteLength > MAXIMUM_JOURNAL_BYTES) {
+        throw new Error("Known-file transaction journal exceeds its byte limit.");
+    }
+    return result;
+}
+async function readEnvelope(path) {
+    let observed;
+    try {
+        observed = await readBoundedRegularFile(path, MAXIMUM_JOURNAL_BYTES);
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+    if (observed.outcome !== "read") {
+        throw new Error("Known-file transaction journal is not one stable regular file.");
+    }
+    const parsed = parseStrictJson(strictUtf8.decode(observed.bytes));
+    assertKnownFileTransactionEnvelope(parsed);
+    if (!observed.bytes.equals(bytes(parsed))) {
+        throw new Error("Known-file transaction journal bytes are not canonical.");
+    }
+    return {
+        envelope: parsed,
+        authority: { digest: digest(observed.bytes), identity: observed.identity }
+    };
+}
+async function prove(path, authority) {
+    const observed = await readBoundedRegularFile(path, MAXIMUM_JOURNAL_BYTES);
+    if (observed.outcome !== "read" || digest(observed.bytes) !== authority.digest ||
+        await pathMatchesRegularFileIdentity(path, authority.identity) !== "match") {
+        throw new Error("Known-file transaction journal authority changed concurrently.");
+    }
+}
+export class NodeKnownFileTransactionJournalStore {
+    #journalPath;
+    #parent;
+    #temporaryPath;
+    constructor(stateDirectory) {
+        this.#parent = stateDirectory;
+        this.#journalPath = join(stateDirectory, FOUNDATION_TRANSACTION_FILE);
+        this.#temporaryPath = join(stateDirectory, KNOWN_FILE_TRANSACTION_TEMPORARY_FILE);
+    }
+    async read() {
+        const canonical = await readEnvelope(this.#journalPath);
+        if (canonical !== undefined) {
+            return canonical;
+        }
+        return readEnvelope(this.#temporaryPath);
+    }
+    async #writeTemporary(envelope) {
+        const content = bytes(envelope);
+        let handle;
+        try {
+            handle = await open(this.#temporaryPath, "wx", 0o600);
+        }
+        catch (error) {
+            if (errorCode(error) === "EEXIST") {
+                const stale = await readEnvelope(this.#temporaryPath);
+                if (stale === undefined) {
+                    throw error;
+                }
+                await prove(this.#temporaryPath, stale.authority);
+                await unlink(this.#temporaryPath);
+                await syncDirectoryStrictly(this.#parent);
+                handle = await open(this.#temporaryPath, "wx", 0o600);
+            }
+            else {
+                throw error;
+            }
+        }
+        try {
+            await handle.writeFile(content);
+            await handle.sync();
+            return { digest: digest(content), identity: await captureFileHandleIdentity(handle) };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async create(envelope) {
+        if (await readEnvelope(this.#journalPath) !== undefined) {
+            throw new Error("Foundation transaction slot is already occupied.");
+        }
+        const authority = await this.#writeTemporary(envelope);
+        await prove(this.#temporaryPath, authority);
+        await rename(this.#temporaryPath, this.#journalPath);
+        await syncDirectoryStrictly(this.#parent);
+        await prove(this.#journalPath, authority);
+        return authority;
+    }
+    async replace(expected, envelope) {
+        await prove(this.#journalPath, expected);
+        const authority = await this.#writeTemporary(envelope);
+        await prove(this.#journalPath, expected);
+        await prove(this.#temporaryPath, authority);
+        await rename(this.#temporaryPath, this.#journalPath);
+        await syncDirectoryStrictly(this.#parent);
+        await prove(this.#journalPath, authority);
+        return authority;
+    }
+    async remove(expected) {
+        await prove(this.#journalPath, expected);
+        await unlink(this.#journalPath);
+        await syncDirectoryStrictly(this.#parent);
+    }
+    async canonicalizeTemporary() {
+        const canonical = await readEnvelope(this.#journalPath);
+        if (canonical !== undefined) {
+            // The canonical envelope remains authoritative during replacement. A
+            // crash can leave an unbound candidate torn or foreign; recovery must
+            // neither parse nor mutate that pathname. It remains preserved evidence
+            // and must not be parsed as authority. Capture a stable regular
+            // candidate by identity and retire it into terminal evidence so neither
+            // a torn write nor a concurrent pathname replacement can block replay.
+            let candidate;
+            try {
+                candidate = await readBoundedRegularFile(this.#temporaryPath, MAXIMUM_JOURNAL_BYTES);
+            }
+            catch (error) {
+                if (errorCode(error) === "ENOENT") {
+                    return;
+                }
+                throw error;
+            }
+            if (candidate.outcome !== "read") {
+                throw new Error("Known-file transaction candidate cannot be retired safely.");
+            }
+            const retired = await cleanupIdentityMatchingOwnedTemporary({
+                allowUnsupportedDirectoryDurability: false,
+                displayPath: KNOWN_FILE_TRANSACTION_TEMPORARY_FILE,
+                expectedIdentity: candidate.identity,
+                parent: this.#parent,
+                rm: async () => { },
+                syncDirectory: syncDirectoryDurably,
+                temporaryPath: this.#temporaryPath
+            });
+            if (retired === "different") {
+                throw new Error("Known-file transaction candidate changed during retirement.");
+            }
+            return;
+        }
+        const temporary = await readEnvelope(this.#temporaryPath);
+        if (temporary === undefined) {
+            throw new Error("Known-file recovery journal is absent.");
+        }
+        await prove(this.#temporaryPath, temporary.authority);
+        await rename(this.#temporaryPath, this.#journalPath);
+        await syncDirectoryStrictly(this.#parent);
+    }
+}
+//# sourceMappingURL=node-known-file-transaction-journal-store.js.map

package/dist/repository-mutation/adapters/node/node-known-file-transaction-journal-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-known-file-transaction-journal-store.js","sourceRoot":"","sources":["../../../../src/repository-mutation/adapters/node/node-known-file-transaction-journal-store.ts"],"names":[],"mappings":"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"}

package/dist/repository-mutation/adapters/node/node-known-file-transaction-receipt.d.ts

@@ -0,0 +1,4 @@
+import type { KnownFileTransactionReceiptV1 } from "../../application/model/known-file-transaction.js";
+import type { KnownFileTransactionJournalV1 } from "../../application/model/known-file-transaction-journal.js";
+export declare function compileRolledBackReceipt(journal: KnownFileTransactionJournalV1): KnownFileTransactionReceiptV1;
+//# sourceMappingURL=node-known-file-transaction-receipt.d.ts.map

package/dist/repository-mutation/adapters/node/node-known-file-transaction-receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-known-file-transaction-receipt.d.ts","sourceRoot":"","sources":["../../../../src/repository-mutation/adapters/node/node-known-file-transaction-receipt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,mDAAmD,CAAC;AACvG,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,2DAA2D,CAAC;AAG/G,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,6BAA6B,GACrC,6BAA6B,CA0C/B"}

package/dist/repository-mutation/adapters/node/node-known-file-transaction-receipt.js

@@ -0,0 +1,43 @@
+import { sha256Json } from "../../../canonical-json.js";
+import { KnownFileTransactionError } from "./node-known-file-transaction-filesystem.js";
+export function compileRolledBackReceipt(journal) {
+    const operations = journal.operations.map((entry, index) => {
+        const planOperation = journal.plan.operations[index];
+        if (entry.state === "already-satisfied") {
+            return Object.freeze({
+                path: entry.path,
+                outcome: "already-satisfied",
+                resultDigest: planOperation.postimage.digest
+            });
+        }
+        if (planOperation.precondition.state === "absent") {
+            return Object.freeze({
+                path: entry.path,
+                outcome: "rolled-back-to-absent"
+            });
+        }
+        if (entry.matchedPreimage === undefined) {
+            throw new KnownFileTransactionError("KNOWN_FILE_JOURNAL_INVALID", `Replacement preimage binding is absent: ${entry.path}.`);
+        }
+        return Object.freeze({
+            path: entry.path,
+            outcome: "rolled-back-to-preimage",
+            resultDigest: planOperation.precondition.acceptedPreimages[entry.matchedPreimage].digest
+        });
+    });
+    const body = {
+        schemaVersion: 1,
+        protocol: "foundation.replace-known-file/v1",
+        planDigest: journal.plan.planDigest,
+        outcome: "rolled-back",
+        operations: Object.freeze(operations)
+    };
+    return Object.freeze({
+        ...body,
+        receiptDigest: sha256Json({
+            domain: "agent-teams.foundation.known-file-transaction-receipt/v1",
+            body
+        })
+    });
+}
+//# sourceMappingURL=node-known-file-transaction-receipt.js.map

package/dist/repository-mutation/adapters/node/node-known-file-transaction-receipt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-known-file-transaction-receipt.js","sourceRoot":"","sources":["../../../../src/repository-mutation/adapters/node/node-known-file-transaction-receipt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAGxD,OAAO,EAAE,yBAAyB,EAAE,MAAM,6CAA6C,CAAC;AAExF,MAAM,UAAU,wBAAwB,CACtC,OAAsC;IAEtC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACzD,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAE,CAAC;QACtD,IAAI,KAAK,CAAC,KAAK,KAAK,mBAAmB,EAAE,CAAC;YACxC,OAAO,MAAM,CAAC,MAAM,CAAC;gBACnB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,OAAO,EAAE,mBAA4B;gBACrC,YAAY,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM;aAC7C,CAAC,CAAC;QACL,CAAC;QACD,IAAI,aAAa,CAAC,YAAY,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YAClD,OAAO,MAAM,CAAC,MAAM,CAAC;gBACnB,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,OAAO,EAAE,uBAAgC;aAC1C,CAAC,CAAC;QACL,CAAC;QACD,IAAI,KAAK,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;YACxC,MAAM,IAAI,yBAAyB,CACjC,4BAA4B,EAC5B,2CAA2C,KAAK,CAAC,IAAI,GAAG,CACzD,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,yBAAkC;YAC3C,YAAY,EAAE,aAAa,CAAC,YAAY,CAAC,iBAAiB,CAAC,KAAK,CAAC,eAAe,CAAE,CAAC,MAAM;SAC1F,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,MAAM,IAAI,GAAG;QACX,aAAa,EAAE,CAAU;QACzB,QAAQ,EAAE,kCAA2C;QACrD,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,UAAU;QACnC,OAAO,EAAE,aAAsB;QAC/B,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC;KACtC,CAAC;IACF,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,IAAI;QACP,aAAa,EAAE,UAAU,CAAC;YACxB,MAAM,EAAE,0DAA0D;YAClE,IAAI;SACL,CAAC;KACH,CAAC,CAAC;AACL,CAAC"}

package/dist/repository-mutation/adapters/node/node-known-file-transaction-recovery.d.ts

@@ -0,0 +1,11 @@
+import type { KnownFileTransactionReceiptV1 } from "../../application/model/known-file-transaction.js";
+export type KnownFileRecoveryFaultInjector = (point: {
+    readonly phase: "after-committed-capture-unlinked" | "after-destination-retired" | "after-rollback-linked" | "after-rollback-capture-unlinked" | "after-retirement-directory-bound" | "after-retirement-captured" | "after-retirement-unlink-authorized";
+    readonly operationIndex: number;
+    readonly path: string;
+}) => Promise<void> | void;
+export declare function recoverKnownFileTransaction(options: {
+    readonly consumerRoot: string;
+    readonly faultInjector?: KnownFileRecoveryFaultInjector;
+}): Promise<KnownFileTransactionReceiptV1>;
+//# sourceMappingURL=node-known-file-transaction-recovery.d.ts.map

package/dist/repository-mutation/adapters/node/node-known-file-transaction-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-known-file-transaction-recovery.d.ts","sourceRoot":"","sources":["../../../../src/repository-mutation/adapters/node/node-known-file-transaction-recovery.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAGV,6BAA6B,EAC9B,MAAM,mDAAmD,CAAC;AA8C3D,MAAM,MAAM,8BAA8B,GAAG,CAAC,KAAK,EAAE;IACnD,QAAQ,CAAC,KAAK,EACV,kCAAkC,GAClC,2BAA2B,GAC3B,uBAAuB,GACvB,iCAAiC,GACjC,kCAAkC,GAClC,2BAA2B,GAC3B,oCAAoC,CAAC;IACzC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAgqC3B,wBAAsB,2BAA2B,CAAC,OAAO,EAAE;IACzD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,8BAA8B,CAAC;CACzD,GAAG,OAAO,CAAC,6BAA6B,CAAC,CAqEzC"}