project-tiny-context-harness 0.8.17 → 0.11.0

package/dist/lib/context-mutation/markdown-link-spans.js

@@ -0,0 +1,179 @@
+import { fromMarkdown } from "mdast-util-from-markdown";
+export function markdownDestinationSpans(content) {
+    const tree = fromMarkdown(content);
+    const spans = [];
+    walk(tree, content, spans);
+    return spans.sort((left, right) => left.start - right.start);
+}
+function walk(node, content, spans) {
+    if (node.type === "link" || node.type === "image") {
+        const located = locateInlineDestination(content, node);
+        if (located)
+            spans.push({
+                ...located,
+                kind: node.type === "link" ? "inline" : "image",
+                ...lineColumn(content, located.start),
+            });
+        if (node.type === "link")
+            return;
+    }
+    else if (node.type === "definition") {
+        const located = locateDefinitionDestination(content, node);
+        if (located)
+            spans.push({
+                ...located,
+                kind: "definition",
+                ...lineColumn(content, located.start),
+            });
+    }
+    else if (node.type === "text" || node.type === "html") {
+        const start = node.position?.start.offset;
+        const end = node.position?.end.offset;
+        if (start !== undefined && end !== undefined)
+            for (const located of locateLocalAngles(content, start, end))
+                spans.push({
+                    ...located,
+                    kind: "angle",
+                    ...lineColumn(content, located.start),
+                });
+    }
+    if (!("children" in node))
+        return;
+    for (const child of node.children)
+        walk(child, content, spans);
+}
+function locateInlineDestination(content, node) {
+    const bounds = nodeBounds(node);
+    if (!bounds)
+        return null;
+    const raw = content.slice(bounds.start, bounds.end);
+    const labelStart = raw.indexOf("[");
+    if (labelStart < 0)
+        return null;
+    const labelEnd = closingBracket(raw, labelStart);
+    if (labelEnd < 0)
+        return null;
+    let cursor = skipWhitespace(raw, labelEnd + 1);
+    if (raw[cursor] !== "(")
+        return null;
+    cursor = skipWhitespace(raw, cursor + 1);
+    return destinationAt(content, raw, bounds.start, cursor, ")");
+}
+function locateDefinitionDestination(content, node) {
+    const bounds = nodeBounds(node);
+    if (!bounds)
+        return null;
+    const raw = content.slice(bounds.start, bounds.end);
+    const labelStart = raw.indexOf("[");
+    if (labelStart < 0)
+        return null;
+    const labelEnd = closingBracket(raw, labelStart);
+    if (labelEnd < 0)
+        return null;
+    let cursor = skipWhitespace(raw, labelEnd + 1);
+    if (raw[cursor] !== ":")
+        return null;
+    cursor = skipWhitespace(raw, cursor + 1);
+    return destinationAt(content, raw, bounds.start, cursor, "line");
+}
+function destinationAt(content, raw, absoluteStart, cursor, terminator) {
+    if (raw[cursor] === "<") {
+        const end = unescapedIndex(raw, ">", cursor + 1);
+        return end < 0
+            ? null
+            : located(content, absoluteStart + cursor + 1, absoluteStart + end);
+    }
+    const start = cursor;
+    let depth = 0;
+    while (cursor < raw.length) {
+        const character = raw[cursor];
+        if (character === "\\") {
+            cursor += 2;
+            continue;
+        }
+        if (character === "(" && terminator === ")")
+            depth += 1;
+        else if (character === ")" && terminator === ")") {
+            if (depth === 0)
+                break;
+            depth -= 1;
+        }
+        else if (/\s/u.test(character) && depth === 0)
+            break;
+        cursor += 1;
+    }
+    return located(content, absoluteStart + start, absoluteStart + cursor);
+}
+function locateLocalAngles(content, start, end) {
+    const result = [];
+    for (let cursor = start; cursor < end; cursor += 1) {
+        if (content[cursor] !== "<")
+            continue;
+        const close = content.indexOf(">", cursor + 1);
+        if (close < 0 || close >= end)
+            break;
+        const candidate = content.slice(cursor + 1, close);
+        if (looksLikeLocalAngle(candidate))
+            result.push(located(content, cursor + 1, close));
+        cursor = close;
+    }
+    return result;
+}
+function located(content, start, end) {
+    return { destination: content.slice(start, end), start, end };
+}
+function closingBracket(raw, start) {
+    let depth = 0;
+    for (let cursor = start; cursor < raw.length; cursor += 1) {
+        if (raw[cursor] === "\\") {
+            cursor += 1;
+            continue;
+        }
+        if (raw[cursor] === "[")
+            depth += 1;
+        else if (raw[cursor] === "]") {
+            depth -= 1;
+            if (depth === 0)
+                return cursor;
+        }
+    }
+    return -1;
+}
+function unescapedIndex(raw, character, start) {
+    for (let cursor = start; cursor < raw.length; cursor += 1) {
+        if (raw[cursor] === "\\")
+            cursor += 1;
+        else if (raw[cursor] === character)
+            return cursor;
+    }
+    return -1;
+}
+function skipWhitespace(raw, start) {
+    let cursor = start;
+    while (cursor < raw.length && /\s/u.test(raw[cursor]))
+        cursor += 1;
+    return cursor;
+}
+function nodeBounds(node) {
+    const start = node.position?.start.offset;
+    const end = node.position?.end.offset;
+    return start === undefined || end === undefined ? null : { start, end };
+}
+function lineColumn(content, offset) {
+    const prefix = content.slice(0, offset);
+    const lines = prefix.split(/\r\n?|\n/u);
+    return {
+        line: lines.length,
+        column: Array.from(lines.at(-1) ?? "").length + 1,
+    };
+}
+function looksLikeLocalAngle(value) {
+    if (!value || Array.from(value).some((point) => /\s/u.test(point)))
+        return false;
+    return (value.startsWith(".") ||
+        value.startsWith("/") ||
+        value.startsWith("project_context") ||
+        value.includes("/") ||
+        value.includes("\\") ||
+        value.toLowerCase().endsWith(".md"));
+}

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

@@ -0,0 +1,13 @@
+import type { MutationFileChange, MutationRecordedFileState, MutationTemporaryState } from "./mutation-types.js";
+export { absentMutationFileState, assertMutationChangesContentState, assertMutationChangesCurrent, captureMutationFileState, mutationFileStateFromBytes, } from "./mutation-file-state.js";
+type MutationSide = "before" | "after";
+type MutationDisposition = MutationSide | "conflict";
+export type MutationBeforeSecondCas = (change: MutationFileChange) => Promise<void>;
+export type MutationAfterTemporaryCreated = (change: MutationFileChange, side: MutationSide) => Promise<void>;
+export declare function mutationTemporaryPath(target: string, transactionId: string, index: number): string;
+export declare function stageMutationTemporary(repository: string, change: MutationFileChange, side?: MutationSide, afterCreated?: MutationAfterTemporaryCreated): Promise<MutationTemporaryState | null>;
+export declare function prepareMutationTemporaryForRecovery(repository: string, change: MutationFileChange, side: MutationSide, beforeSecondCas?: MutationBeforeSecondCas, afterCreated?: MutationAfterTemporaryCreated): Promise<MutationTemporaryState | null>;
+export declare function applyMutationChangeForward(repository: string, change: MutationFileChange, beforeSecondCas?: MutationBeforeSecondCas): Promise<MutationRecordedFileState>;
+export declare function applyMutationChangeBackward(repository: string, change: MutationFileChange, beforeSecondCas?: MutationBeforeSecondCas): Promise<MutationRecordedFileState>;
+export declare function mutationChangeDisposition(repository: string, change: MutationFileChange): Promise<MutationDisposition>;
+export declare function cleanupMutationTemporary(repository: string, change: MutationFileChange): Promise<void>;

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>;