project-tiny-context-harness 0.8.17 → 0.12.0

package/dist/lib/context-mutation/mutation-cas.js

@@ -0,0 +1,365 @@
+import { chmod, link, lstat, open, rename, unlink } from "node:fs/promises";
+import path from "node:path";
+import { assertSafeRepositoryFilePath, resolveInsideRepository, } from "../repository-path-safety.js";
+import { sha256Hex } from "../strict-codec.js";
+import { captureMutationFileState, mutationPhysicalPath, mutationRecordedFileState, sameMutationRecordedState, } from "./mutation-file-state.js";
+export { absentMutationFileState, assertMutationChangesContentState, assertMutationChangesCurrent, captureMutationFileState, mutationFileStateFromBytes, } from "./mutation-file-state.js";
+export function mutationTemporaryPath(target, transactionId, index) {
+    const parent = path.posix.dirname(target);
+    const name = path.posix.basename(target);
+    return `${parent}/.${name}.ty-context-mutation-${transactionId.slice(0, 16)}-${index}.tmp`;
+}
+export async function stageMutationTemporary(repository, change, side = "after", afterCreated) {
+    const state = change[side];
+    if (!state.exists)
+        return null;
+    if (!change.temporary_path)
+        invalid(`temporary_path_missing:${change.path}`);
+    const temporary = await assertSafeRepositoryFilePath(repository, change.temporary_path, "context_mutation_temporary", { destinationMayBeAbsent: true, allowHardlinks: true });
+    if (temporary.status) {
+        const current = await captureMutationFileState(repository, change.temporary_path, { allow_hardlinks: true });
+        if (change.temporary_state?.side === side &&
+            sameMutationRecordedState(current, change.temporary_state.state))
+            return change.temporary_state;
+        invalid(`temporary_collision:${change.temporary_path}`);
+    }
+    const handle = await open(temporary.absolute, "wx", state.mode ?? 0o666);
+    try {
+        await handle.writeFile(stateBytes(state));
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    if (state.mode !== null)
+        await chmod(temporary.absolute, state.mode);
+    await afterCreated?.(change, side);
+    const captured = await captureMutationFileState(repository, change.temporary_path, { allow_hardlinks: true });
+    if (!samePayload(captured, state) || captured.identity?.nlink !== "1")
+        invalid(`temporary_readback_mismatch:${change.temporary_path}`);
+    return { side, state: mutationRecordedFileState(captured) };
+}
+export async function prepareMutationTemporaryForRecovery(repository, change, side, beforeSecondCas, afterCreated) {
+    const desired = change[side];
+    if (!change.temporary_path)
+        invalid(`temporary_path_missing:${change.path}`);
+    const temporary = await captureMutationFileState(repository, change.temporary_path, { allow_hardlinks: true });
+    if (temporary.exists) {
+        if (desired.exists &&
+            change.temporary_state?.side === side &&
+            sameMutationRecordedState(temporary, change.temporary_state.state))
+            return change.temporary_state;
+        if (desired.exists &&
+            change.temporary_state?.side === side &&
+            isOwnedDeletionRemainder(temporary, change.temporary_state.state))
+            return change.temporary_state;
+        await removeOwnedTemporary(repository, change, temporary);
+    }
+    if (desired.exists)
+        return stageMutationTemporary(repository, change, side, afterCreated);
+    return stageDeletionTombstone(repository, change, side, beforeSecondCas, afterCreated);
+}
+export async function applyMutationChangeForward(repository, change, beforeSecondCas) {
+    return applyMutationState(repository, change, "before", "after", beforeSecondCas);
+}
+export async function applyMutationChangeBackward(repository, change, beforeSecondCas) {
+    return applyMutationState(repository, change, "after", "before", beforeSecondCas);
+}
+export async function mutationChangeDisposition(repository, change) {
+    await assertNoUnrecordedTemporary(repository, change);
+    const current = await captureMutationFileState(repository, mutationPhysicalPath(change), {
+        allow_hardlinks: true,
+    });
+    if (matchesRecordedSide(current, change, "before"))
+        return "before";
+    if (matchesRecordedSide(current, change, "after"))
+        return "after";
+    return ((await ownedTemporaryTransition(repository, change, current)) ?? "conflict");
+}
+export async function cleanupMutationTemporary(repository, change) {
+    if (!change.temporary_path)
+        return;
+    const absolute = resolveInsideRepository(repository, change.temporary_path, "context_mutation_temporary_cleanup");
+    const status = await lstat(absolute).catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (!status)
+        return;
+    const current = await captureMutationFileState(repository, change.temporary_path, { allow_hardlinks: true });
+    await removeOwnedTemporary(repository, change, current);
+}
+async function applyMutationState(repository, change, expectedSide, desiredSide, beforeSecondCas) {
+    let disposition = await mutationChangeDisposition(repository, change);
+    if (disposition === desiredSide)
+        return captureDesiredEndpoint(repository, change, desiredSide);
+    if (disposition !== expectedSide)
+        invalid(`recovery_conflict:${change.path}`);
+    const desired = change[desiredSide];
+    const target = await assertSafeRepositoryFilePath(repository, mutationPhysicalPath(change), "context_mutation_commit_target", { destinationMayBeAbsent: true, allowHardlinks: !desired.exists });
+    if (desired.exists)
+        await assertTemporaryReady(repository, change, desiredSide);
+    else
+        await assertDeletionTombstoneReady(repository, change, expectedSide);
+    // This second cooperative CAS closes changes made during staging and path
+    // acquisition. Publication remains a narrow rename/link/unlink window, not
+    // a claim of hostile-writer filesystem atomicity.
+    if (desired.exists)
+        await beforeSecondCas?.(change);
+    disposition = await mutationChangeDisposition(repository, change);
+    if (disposition === desiredSide)
+        return captureDesiredEndpoint(repository, change, desiredSide);
+    if (disposition !== expectedSide)
+        invalid(`second_cas_conflict:${change.path}`);
+    if (!desired.exists) {
+        if (!target.status)
+            invalid(`deletion_target_missing:${change.path}`);
+        await unlink(target.absolute);
+    }
+    else {
+        const temporary = resolveInsideRepository(repository, change.temporary_path, "context_mutation_commit_temporary");
+        if (change[expectedSide].exists)
+            await rename(temporary, target.absolute);
+        else {
+            try {
+                await link(temporary, target.absolute);
+            }
+            catch (error) {
+                if (error.code === "EEXIST")
+                    invalid(`destination_collision:${change.path}`);
+                throw error;
+            }
+            await unlink(temporary);
+        }
+    }
+    await syncParentDirectory(path.dirname(target.absolute));
+    return captureDesiredEndpoint(repository, change, desiredSide);
+}
+async function captureDesiredEndpoint(repository, change, side) {
+    const current = await captureMutationFileState(repository, mutationPhysicalPath(change), {
+        allow_hardlinks: true,
+    });
+    const desired = change[side];
+    if (!samePayload(current, desired))
+        invalid(`post_commit_readback_mismatch:${change.path}`);
+    const transition = await ownedTemporaryTransition(repository, change, current);
+    const recorded = side === "before" ? change.published_before : change.published_after;
+    if (transition !== side &&
+        !(recorded && sameMutationRecordedState(current, recorded)) &&
+        !(desired.exists && sameMutationRecordedState(current, desired)))
+        invalid(`post_commit_identity_mismatch:${change.path}`);
+    return mutationRecordedFileState(current);
+}
+async function assertTemporaryReady(repository, change, side) {
+    if (!change.temporary_path || change.temporary_state?.side !== side)
+        invalid(`temporary_state_missing:${change.path}`);
+    const temporary = await captureMutationFileState(repository, change.temporary_path, { allow_hardlinks: true });
+    if (!((sameMutationRecordedState(temporary, change.temporary_state.state) &&
+        temporary.identity?.nlink === "1") ||
+        isOwnedDeletionRemainder(temporary, change.temporary_state.state)))
+        invalid(`temporary_identity_changed:${change.temporary_path}`);
+}
+function matchesRecordedSide(current, change, side) {
+    const semantic = change[side];
+    const published = side === "before" ? change.published_before : change.published_after;
+    if (published && sameMutationRecordedState(current, published))
+        return true;
+    if (semantic.exists)
+        return sameMutationRecordedState(current, semantic);
+    if (side !== "before")
+        return false;
+    const oppositePublished = change.published_after;
+    return (oppositePublished === null && sameMutationRecordedState(current, semantic));
+}
+async function ownedTemporaryTransition(repository, change, current) {
+    const prepared = change.temporary_state;
+    if (!prepared || !change.temporary_path)
+        return null;
+    const temporary = await captureMutationFileState(repository, change.temporary_path, { allow_hardlinks: true });
+    if (prepared.state.identity?.nlink === "2")
+        return ownedDeletionTombstoneTransition(current, temporary, prepared);
+    if (!current.exists ||
+        !samePayload(current, change[prepared.side]) ||
+        !sameFileObject(current, prepared.state))
+        return null;
+    if (!temporary.exists)
+        return current.identity?.nlink === "1" ? prepared.side : null;
+    if (current.identity?.nlink === "2" &&
+        temporary.identity?.nlink === "2" &&
+        samePayload(temporary, change[prepared.side]) &&
+        sameFileObject(current, temporary))
+        return prepared.side;
+    return null;
+}
+function ownedDeletionTombstoneTransition(current, temporary, prepared) {
+    if (current.exists &&
+        temporary.exists &&
+        sameMutationRecordedState(current, prepared.state) &&
+        sameMutationRecordedState(temporary, prepared.state))
+        return prepared.side;
+    if (!current.exists &&
+        temporary.exists &&
+        isOwnedDeletionRemainder(temporary, prepared.state))
+        return oppositeSide(prepared.side);
+    if (current.exists &&
+        !temporary.exists &&
+        isOwnedDeletionRemainder(current, prepared.state))
+        return prepared.side;
+    return null;
+}
+async function removeOwnedTemporary(repository, change, temporary) {
+    if (!change.temporary_path || !change.temporary_state)
+        invalid(`temporary_identity_unrecorded:${change.temporary_path ?? change.path}`);
+    const exact = sameMutationRecordedState(temporary, change.temporary_state.state);
+    let linkedPair = false;
+    if (!exact && temporary.identity?.nlink === "2") {
+        const target = await captureMutationFileState(repository, mutationPhysicalPath(change), { allow_hardlinks: true });
+        linkedPair =
+            target.identity?.nlink === "2" &&
+                sameFileObject(target, temporary) &&
+                samePayload(temporary, change[change.temporary_state.side]) &&
+                (await ownedTemporaryTransition(repository, change, target)) ===
+                    change.temporary_state.side;
+    }
+    const deletionRemainder = !exact &&
+        change.temporary_state.state.identity?.nlink === "2" &&
+        isOwnedDeletionRemainder(temporary, change.temporary_state.state) &&
+        !(await captureMutationFileState(repository, mutationPhysicalPath(change), {
+            allow_hardlinks: true,
+        })).exists;
+    if (!exact && !linkedPair && !deletionRemainder)
+        invalid(`temporary_identity_changed:${change.temporary_path}`);
+    const absolute = resolveInsideRepository(repository, change.temporary_path, "context_mutation_temporary_cleanup");
+    await unlink(absolute);
+    await syncParentDirectory(path.dirname(absolute));
+}
+function samePayload(current, expected) {
+    return (current.exists === expected.exists &&
+        current.sha256 === expected.sha256 &&
+        current.mode === expected.mode);
+}
+function sameFileObject(current, expected) {
+    const left = current.identity;
+    const right = expected.identity;
+    return (left !== null &&
+        right !== null &&
+        left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.size === right.size &&
+        left.mtime_ns === right.mtime_ns);
+}
+async function stageDeletionTombstone(repository, change, desiredSide, beforeSecondCas, afterCreated) {
+    const expectedSide = oppositeSide(desiredSide);
+    if (!change[expectedSide].exists || change[desiredSide].exists)
+        invalid(`deletion_transition_invalid:${change.path}`);
+    let disposition = await mutationChangeDisposition(repository, change);
+    if (disposition !== expectedSide)
+        invalid(`recovery_conflict:${change.path}`);
+    await beforeSecondCas?.(change);
+    disposition = await mutationChangeDisposition(repository, change);
+    if (disposition !== expectedSide)
+        invalid(`second_cas_conflict:${change.path}`);
+    const beforeLink = await captureMutationFileState(repository, mutationPhysicalPath(change));
+    if ((await mutationChangeDisposition(repository, change)) !== expectedSide)
+        invalid(`second_cas_conflict:${change.path}`);
+    const target = await assertSafeRepositoryFilePath(repository, mutationPhysicalPath(change), "context_mutation_deletion_target", { destinationMayBeAbsent: false });
+    const temporary = await assertSafeRepositoryFilePath(repository, change.temporary_path, "context_mutation_deletion_tombstone", { destinationMayBeAbsent: true, allowHardlinks: true });
+    if (!target.status)
+        invalid(`deletion_target_missing:${change.path}`);
+    if (temporary.status)
+        invalid(`temporary_collision:${change.temporary_path}`);
+    try {
+        await link(target.absolute, temporary.absolute);
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            invalid(`temporary_collision:${change.temporary_path}`);
+        throw error;
+    }
+    await afterCreated?.(change, expectedSide);
+    const [targetState, temporaryState] = await Promise.all([
+        captureMutationFileState(repository, mutationPhysicalPath(change), {
+            allow_hardlinks: true,
+        }),
+        captureMutationFileState(repository, change.temporary_path, {
+            allow_hardlinks: true,
+        }),
+    ]);
+    if (targetState.identity?.nlink !== "2" ||
+        temporaryState.identity?.nlink !== "2" ||
+        !sameMutationRecordedState(targetState, temporaryState) ||
+        !samePayload(targetState, change[expectedSide]) ||
+        !sameFileObject(targetState, beforeLink))
+        invalid(`deletion_tombstone_readback_mismatch:${change.path}`);
+    await syncParentDirectory(path.dirname(temporary.absolute));
+    return {
+        side: expectedSide,
+        state: mutationRecordedFileState(temporaryState),
+    };
+}
+async function assertDeletionTombstoneReady(repository, change, expectedSide) {
+    const prepared = change.temporary_state;
+    if (!change.temporary_path ||
+        !prepared ||
+        prepared.side !== expectedSide ||
+        prepared.state.identity?.nlink !== "2")
+        invalid(`deletion_tombstone_missing:${change.path}`);
+    const [target, temporary] = await Promise.all([
+        captureMutationFileState(repository, mutationPhysicalPath(change), {
+            allow_hardlinks: true,
+        }),
+        captureMutationFileState(repository, change.temporary_path, {
+            allow_hardlinks: true,
+        }),
+    ]);
+    if (!sameMutationRecordedState(target, prepared.state) ||
+        !sameMutationRecordedState(temporary, prepared.state))
+        invalid(`deletion_tombstone_identity_changed:${change.path}`);
+}
+async function assertNoUnrecordedTemporary(repository, change) {
+    if (!change.temporary_path || change.temporary_state)
+        return;
+    const temporary = await captureMutationFileState(repository, change.temporary_path, { allow_hardlinks: true });
+    if (temporary.exists)
+        invalid(`temporary_identity_unrecorded:${change.temporary_path}:manual_recovery_required_restore_exact_path_state_and_remove_only_the_verified_orphan`);
+}
+function isOwnedDeletionRemainder(current, recorded) {
+    return (current.exists &&
+        current.identity?.nlink === "1" &&
+        recorded.identity?.nlink === "2" &&
+        current.sha256 === recorded.sha256 &&
+        current.mode === recorded.mode &&
+        sameFileObject(current, recorded));
+}
+function oppositeSide(side) {
+    return side === "before" ? "after" : "before";
+}
+async function syncParentDirectory(directory) {
+    let handle;
+    try {
+        handle = await open(directory, "r");
+        await handle.sync();
+    }
+    catch (error) {
+        const code = error.code;
+        if (process.platform === "win32" &&
+            ["EACCES", "EINVAL", "EPERM"].includes(code ?? ""))
+            return;
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function stateBytes(state) {
+    if (!state.exists || state.bytes_base64 === null || state.sha256 === null)
+        invalid("file_state_bytes_missing");
+    const bytes = Buffer.from(state.bytes_base64, "base64");
+    if (sha256Hex(bytes) !== state.sha256)
+        invalid("file_state_digest_mismatch");
+    return bytes;
+}
+function invalid(reason) {
+    throw new Error(`context_mutation_invalid:${reason}`);
+}

package/dist/lib/context-mutation/mutation-command-support.d.ts

@@ -0,0 +1,12 @@
+import type { ContextCatalog } from "../context-catalog/catalog-types.js";
+export declare function assertNoUnfinishedContextMutation(repository: string): Promise<void>;
+export declare function loadMutationCatalog(repository: string, fileOverrides?: ReadonlyMap<string, Uint8Array | null>, directoryOverrides?: ReadonlySet<string>): Promise<ContextCatalog>;
+export declare function assertMutationCatalogValid(catalog: ContextCatalog, prefix: string): void;
+export declare function mutationStateBytes(state: {
+    bytes_base64: string | null;
+}): Buffer;
+export declare function decodeMutationUtf8(bytes: Uint8Array, file: string): string;
+export declare function sameMutationArray(left: string[], right: string[]): boolean;
+export declare function mutationCatalogFailure(messageText: string, cause?: unknown): never;
+export declare function mutationIoFailure(messageText: string, cause?: unknown): never;
+export declare function mutationMessage(error: unknown): string;

package/dist/lib/context-mutation/mutation-command-support.js

@@ -0,0 +1,57 @@
+import { CLI_EXIT_CODES, CliCommandError } from "../cli-exit.js";
+import { catalogErrors } from "../context-catalog/catalog-diagnostics.js";
+import { loadContextCatalog } from "../context-catalog/catalog-load.js";
+import { readContextMutationJournal } from "./mutation-journal.js";
+export async function assertNoUnfinishedContextMutation(repository) {
+    let journal;
+    try {
+        journal = await readContextMutationJournal(repository);
+    }
+    catch (error) {
+        mutationIoFailure(`unable to inspect Context mutation journal: ${mutationMessage(error)}`, error);
+    }
+    if (journal)
+        mutationIoFailure(`unfinished Context mutation ${journal.transaction_id} exists; run ty-context context transaction status and then rollback or complete`);
+}
+export async function loadMutationCatalog(repository, fileOverrides, directoryOverrides) {
+    try {
+        return await loadContextCatalog(repository, {
+            file_overrides: fileOverrides,
+            directory_overrides: directoryOverrides,
+        });
+    }
+    catch (error) {
+        mutationIoFailure(`unable to load Context Catalog: ${mutationMessage(error)}`, error);
+    }
+}
+export function assertMutationCatalogValid(catalog, prefix) {
+    const errors = catalogErrors(catalog.diagnostics);
+    if (errors.length)
+        mutationCatalogFailure(`${prefix}: ${errors.join("; ")}`);
+}
+export function mutationStateBytes(state) {
+    if (state.bytes_base64 === null)
+        mutationIoFailure("mutation snapshot bytes are missing");
+    return Buffer.from(state.bytes_base64, "base64");
+}
+export function decodeMutationUtf8(bytes, file) {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch (error) {
+        mutationCatalogFailure(`${file} must be valid UTF-8`, error);
+    }
+}
+export function sameMutationArray(left, right) {
+    return (left.length === right.length &&
+        left.every((value, index) => value === right[index]));
+}
+export function mutationCatalogFailure(messageText, cause) {
+    throw new CliCommandError(CLI_EXIT_CODES.catalog, messageText, { cause });
+}
+export function mutationIoFailure(messageText, cause) {
+    throw new CliCommandError(CLI_EXIT_CODES.io, messageText, { cause });
+}
+export function mutationMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lib/context-mutation/mutation-commit.d.ts

@@ -0,0 +1,12 @@
+import { type MutationBeforeSecondCas } from "./mutation-cas.js";
+import type { ContextMutationJournal, ContextMutationPlan } from "./mutation-types.js";
+export type MutationFaultPoint = "journal_created" | "prepared" | "before_validation" | `temporary_created_before_identity:${string}` | `published_before_journal:${string}` | `applied:${string}`;
+export type MutationBarrier = (point: MutationFaultPoint, change?: ContextMutationJournal["files"][number]) => Promise<void>;
+export interface ExecuteContextMutationOptions {
+    fault_after?: MutationFaultPoint;
+    before_second_cas?: MutationBeforeSecondCas;
+    barrier?: MutationBarrier;
+}
+export declare function executeContextMutationPlan(repository: string, plan: ContextMutationPlan, options?: ExecuteContextMutationOptions): Promise<void>;
+export declare function finishContextMutation(repository: string, journal: ContextMutationJournal): Promise<void>;
+export declare function cleanupContextMutationTemporaries(repository: string, journal: ContextMutationJournal): Promise<void>;

package/dist/lib/context-mutation/mutation-commit.js

@@ -0,0 +1,89 @@
+import { applyMutationChangeForward, assertMutationChangesCurrent, assertMutationChangesContentState, cleanupMutationTemporary, mutationChangeDisposition, prepareMutationTemporaryForRecovery, stageMutationTemporary, } from "./mutation-cas.js";
+import { assertMutationDirectoriesAbsent, prepareMutationDirectories, } from "./mutation-directories.js";
+import { createContextMutationJournal, removeContextMutationJournal, updateContextMutationJournal, } from "./mutation-journal.js";
+import { withContextMutationInterlock } from "./mutation-interlock.js";
+import { validateLiveContextMutation } from "./mutation-live-validation.js";
+export async function executeContextMutationPlan(repository, plan, options = {}) {
+    await withContextMutationInterlock(repository, async () => executeContextMutationPlanLocked(repository, plan, options));
+}
+async function executeContextMutationPlanLocked(repository, plan, options) {
+    await assertMutationDirectoriesAbsent(repository, plan.directories);
+    await assertMutationChangesCurrent(repository, plan.files);
+    let journal = await createContextMutationJournal(repository, plan);
+    await checkpoint(options, "journal_created");
+    await prepareMutationDirectories(repository, plan.directories);
+    for (const change of ordered(journal.files)) {
+        const temporary = await stageMutationTemporary(repository, change, "after", temporaryCreatedCheckpoint(options));
+        if (!temporary)
+            continue;
+        const successor = replaceJournalFile(journal, change.path, {
+            temporary_state: temporary,
+        });
+        journal = await updateContextMutationJournal(repository, journal, successor, ["planning"]);
+    }
+    journal = await updateContextMutationJournal(repository, journal, { ...journal, state: "prepared" }, ["planning"]);
+    await checkpoint(options, "prepared");
+    await assertMutationChangesCurrent(repository, plan.files);
+    journal = await updateContextMutationJournal(repository, journal, { ...journal, state: "committing" }, ["prepared"]);
+    for (const planned of ordered(journal.files)) {
+        let change = journal.files.find((entry) => entry.path === planned.path);
+        if (!change.after.exists &&
+            (await mutationChangeDisposition(repository, change)) !== "after") {
+            const temporary = await prepareMutationTemporaryForRecovery(repository, change, "after", options.before_second_cas, temporaryCreatedCheckpoint(options));
+            const successor = replaceJournalFile(journal, change.path, {
+                temporary_state: temporary,
+            });
+            journal = await updateContextMutationJournal(repository, journal, successor, ["committing"]);
+            change = journal.files.find((entry) => entry.path === planned.path);
+        }
+        const published = await applyMutationChangeForward(repository, change, options.before_second_cas);
+        await checkpoint(options, `published_before_journal:${change.path}`, change);
+        let successor = replaceJournalFile(journal, change.path, {
+            published_after: published,
+        });
+        successor = markApplied(successor, change);
+        journal = await updateContextMutationJournal(repository, journal, successor, ["committing"]);
+        await checkpoint(options, `applied:${change.path}`, change);
+    }
+    journal = await updateContextMutationJournal(repository, journal, { ...journal, state: "validating" }, ["committing"]);
+    await checkpoint(options, "before_validation");
+    await assertMutationChangesContentState(repository, journal.files, "after");
+    await validateLiveContextMutation(repository, journal);
+    await assertMutationChangesContentState(repository, journal.files, "after");
+    await finishContextMutation(repository, journal);
+}
+function replaceJournalFile(journal, file, replacement) {
+    return {
+        ...journal,
+        files: journal.files.map((entry) => entry.path === file ? { ...entry, ...replacement } : entry),
+    };
+}
+export async function finishContextMutation(repository, journal) {
+    await cleanupContextMutationTemporaries(repository, journal);
+    await removeContextMutationJournal(repository, journal);
+}
+export async function cleanupContextMutationTemporaries(repository, journal) {
+    for (const change of ordered(journal.files))
+        await cleanupMutationTemporary(repository, change);
+}
+function ordered(values) {
+    return [...values].sort((left, right) => left.commit_order - right.commit_order);
+}
+function markApplied(journal, change) {
+    if (journal.applied_paths.includes(change.path))
+        return journal;
+    if (journal.applied_paths.length !== change.commit_order)
+        throw new Error(`context_mutation_invalid:journal_applied_paths_not_prefix:${change.path}`);
+    return {
+        ...journal,
+        applied_paths: [...journal.applied_paths, change.path],
+    };
+}
+function temporaryCreatedCheckpoint(options) {
+    return async (change) => checkpoint(options, `temporary_created_before_identity:${change.path}`, change);
+}
+async function checkpoint(options, point, change) {
+    await options.barrier?.(point, change);
+    if (options.fault_after === point)
+        throw new Error(`context_mutation_fault_injected:${point}`);
+}

package/dist/lib/context-mutation/mutation-directories.d.ts

@@ -0,0 +1,5 @@
+import type { MutationDirectoryChange, MutationDirectoryStatus } from "./mutation-types.js";
+export declare function assertMutationDirectoriesAbsent(repository: string, directories: MutationDirectoryChange[]): Promise<void>;
+export declare function prepareMutationDirectories(repository: string, directories: MutationDirectoryChange[]): Promise<void>;
+export declare function rollbackMutationDirectories(repository: string, directories: MutationDirectoryChange[]): Promise<void>;
+export declare function mutationDirectoryStatus(repository: string, entry: MutationDirectoryChange): Promise<MutationDirectoryStatus>;

package/dist/lib/context-mutation/mutation-directories.js

@@ -0,0 +1,56 @@
+import { lstat, rmdir } from "node:fs/promises";
+import path from "node:path";
+import { assertProtectedRepositoryDirectory, ensureSafeRepositoryDirectory, resolveInsideRepository, } from "../repository-path-safety.js";
+export async function assertMutationDirectoriesAbsent(repository, directories) {
+    const conflicts = [];
+    for (const entry of directories)
+        if ((await mutationDirectoryStatus(repository, entry)).state !== "absent")
+            conflicts.push(entry.path);
+    if (conflicts.length)
+        invalid(`directory_cas_conflict:${conflicts.join(",")}`);
+}
+export async function prepareMutationDirectories(repository, directories) {
+    for (const entry of directories)
+        await ensureSafeRepositoryDirectory(repository, entry.path, "context_mutation_directory");
+}
+export async function rollbackMutationDirectories(repository, directories) {
+    for (const entry of [...directories].reverse()) {
+        const status = await mutationDirectoryStatus(repository, entry);
+        if (status.state === "absent")
+            continue;
+        if (status.state !== "directory")
+            invalid(`directory_recovery_conflict:${entry.path}`);
+        const absolute = await assertProtectedRepositoryDirectory(repository, path.join(repository, ...entry.path.split("/")), "context_mutation_directory_rollback");
+        try {
+            await rmdir(absolute);
+        }
+        catch (error) {
+            if (error.code === "ENOTEMPTY")
+                invalid(`directory_recovery_not_empty:${entry.path}`);
+            throw error;
+        }
+    }
+}
+export async function mutationDirectoryStatus(repository, entry) {
+    const absolute = resolveInsideRepository(repository, entry.path, "context_mutation_directory_status");
+    const status = await lstat(absolute).catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (!status)
+        return { path: entry.path, state: "absent" };
+    if (status.isDirectory() && !status.isSymbolicLink()) {
+        try {
+            await assertProtectedRepositoryDirectory(repository, absolute, "context_mutation_directory_status");
+            return { path: entry.path, state: "directory" };
+        }
+        catch {
+            return { path: entry.path, state: "conflict" };
+        }
+    }
+    return { path: entry.path, state: "conflict" };
+}
+function invalid(reason) {
+    throw new Error(`context_mutation_invalid:${reason}`);
+}

package/dist/lib/context-mutation/mutation-file-state.d.ts

@@ -0,0 +1,14 @@
+import type { MutationFileChange, MutationFileIdentity, MutationRecordedFileState, MutationFileState } from "./mutation-types.js";
+export declare function captureMutationFileState(repository: string, relative: string, options?: {
+    allow_hardlinks?: boolean;
+}): Promise<MutationFileState>;
+export declare function mutationFileStateFromBytes(bytes: Uint8Array, mode: number): MutationFileState;
+export declare function absentMutationFileState(): MutationFileState;
+export declare function assertMutationChangesCurrent(repository: string, changes: MutationFileChange[]): Promise<void>;
+export declare function assertMutationChangesContentState(repository: string, changes: MutationFileChange[], side: "before" | "after"): Promise<void>;
+export declare function sameMutationContentState(left: MutationFileState, right: MutationFileState): boolean;
+export declare function mutationPhysicalPath(change: Pick<MutationFileChange, "path" | "physical_path">): string;
+export declare function mutationRecordedFileState(state: MutationFileState): MutationRecordedFileState;
+export declare function sameMutationRecordedState(current: MutationFileState, expected: MutationRecordedFileState | MutationFileState): boolean;
+export declare function sameMutationSnapshot(current: MutationFileState, expected: MutationFileState): boolean;
+export declare function sameMutationIdentity(left: MutationFileIdentity | null, right: MutationFileIdentity | null): boolean;