project-tiny-context-harness 0.8.17 → 0.12.0

package/dist/lib/context-mutation/mutation-file-state.js

@@ -0,0 +1,137 @@
+import { lstat, readFile } from "node:fs/promises";
+import { assertSafeRepositoryFilePath } from "../repository-path-safety.js";
+import { sha256Hex } from "../strict-codec.js";
+export async function captureMutationFileState(repository, relative, options = {}) {
+    let safe;
+    try {
+        safe = await assertSafeRepositoryFilePath(repository, relative, "context_mutation_snapshot", {
+            destinationMayBeAbsent: true,
+            allowHardlinks: options.allow_hardlinks === true,
+        });
+    }
+    catch (error) {
+        if (/^protected_input_parent_not_found:/u.test(message(error)))
+            return absentMutationFileState();
+        throw error;
+    }
+    if (!safe.status)
+        return absentMutationFileState();
+    const before = await lstat(safe.absolute, { bigint: true });
+    if (!before.isFile() || before.isSymbolicLink())
+        invalid(`snapshot_target_unsafe:${relative}`);
+    if (!options.allow_hardlinks && before.nlink !== 1n)
+        invalid(`snapshot_target_hardlinked:${relative}`);
+    const bytes = await readFile(safe.absolute);
+    const after = await lstat(safe.absolute, { bigint: true });
+    if (!sameBigIntStatus(before, after))
+        invalid(`snapshot_changed_during_read:${relative}`);
+    if (after.ino === 0n)
+        invalid(`snapshot_identity_unavailable:${relative}`);
+    return {
+        exists: true,
+        sha256: sha256Hex(bytes),
+        bytes_base64: bytes.toString("base64"),
+        mode: Number(after.mode & 511n),
+        identity: fileIdentity(after),
+    };
+}
+export function mutationFileStateFromBytes(bytes, mode) {
+    const buffer = Buffer.from(bytes);
+    return {
+        exists: true,
+        sha256: sha256Hex(buffer),
+        bytes_base64: buffer.toString("base64"),
+        mode: mode & 0o777,
+        identity: null,
+    };
+}
+export function absentMutationFileState() {
+    return {
+        exists: false,
+        sha256: null,
+        bytes_base64: null,
+        mode: null,
+        identity: null,
+    };
+}
+export async function assertMutationChangesCurrent(repository, changes) {
+    const conflicts = [];
+    for (const change of changes) {
+        const current = await captureMutationFileState(repository, mutationPhysicalPath(change));
+        if (!sameMutationSnapshot(current, change.before))
+            conflicts.push(change.path);
+    }
+    if (conflicts.length)
+        invalid(`cas_conflict:${conflicts.sort().join(",")}`);
+}
+export async function assertMutationChangesContentState(repository, changes, side) {
+    const conflicts = [];
+    for (const change of changes) {
+        const expected = side === "before"
+            ? (change.published_before ?? change.before)
+            : (change.published_after ?? change.after);
+        const current = await captureMutationFileState(repository, mutationPhysicalPath(change));
+        if (!sameMutationRecordedState(current, expected))
+            conflicts.push(change.path);
+    }
+    if (conflicts.length)
+        invalid(`${side}_state_conflict:${conflicts.sort().join(",")}`);
+}
+export function sameMutationContentState(left, right) {
+    return left.exists === right.exists && left.sha256 === right.sha256;
+}
+export function mutationPhysicalPath(change) {
+    return change.physical_path ?? change.path;
+}
+export function mutationRecordedFileState(state) {
+    return {
+        exists: state.exists,
+        sha256: state.sha256,
+        mode: state.mode,
+        identity: state.identity,
+    };
+}
+export function sameMutationRecordedState(current, expected) {
+    return (current.exists === expected.exists &&
+        current.sha256 === expected.sha256 &&
+        current.mode === expected.mode &&
+        sameMutationIdentity(current.identity, expected.identity));
+}
+export function sameMutationSnapshot(current, expected) {
+    return sameMutationRecordedState(current, expected);
+}
+export function sameMutationIdentity(left, right) {
+    if (left === null || right === null)
+        return left === right;
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.nlink === right.nlink &&
+        left.size === right.size &&
+        left.mtime_ns === right.mtime_ns &&
+        left.ctime_ns === right.ctime_ns);
+}
+function fileIdentity(status) {
+    return {
+        dev: status.dev.toString(10),
+        ino: status.ino.toString(10),
+        nlink: status.nlink.toString(10),
+        size: status.size.toString(10),
+        mtime_ns: status.mtimeNs.toString(10),
+        ctime_ns: status.ctimeNs.toString(10),
+    };
+}
+function sameBigIntStatus(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.nlink === right.nlink &&
+        left.size === right.size &&
+        left.mode === right.mode &&
+        left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs);
+}
+function invalid(reason) {
+    throw new Error(`context_mutation_invalid:${reason}`);
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1 @@
+export declare function withContextMutationInterlock<T>(repository: string, action: () => Promise<T>): Promise<T>;

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

@@ -0,0 +1,9 @@
+import { assertSupportedSchema } from "../schema-guard.js";
+import { withMaintenanceLock } from "../maintenance-lock.js";
+export async function withContextMutationInterlock(repository, action) {
+    await assertSupportedSchema(repository, "context mutation/recovery");
+    return withMaintenanceLock(repository, "context_mutation", async () => {
+        await assertSupportedSchema(repository, "context mutation/recovery");
+        return action();
+    });
+}

package/dist/lib/context-mutation/mutation-journal-file-validation.d.ts

@@ -0,0 +1 @@
+export declare function validateJournalFiles(value: unknown, transactionId: string, maxFiles: number, maxStoredBytes: number, physicalPathMode: "forbidden-v2" | "required-v3"): Record<string, unknown>[];

package/dist/lib/context-mutation/mutation-journal-file-validation.js

@@ -0,0 +1,106 @@
+import { assertJournalMutationTarget, assertJournalRelative, invalidJournal, isJournalRecord, requiredJournalInteger, requiredJournalString, sameJournalFileState, sameJournalRecordedPayload, validateJournalFileState, validateJournalRecordedFileState, validateJournalTemporaryPath, } from "./mutation-journal-validation-support.js";
+import { normalizeContextPath } from "../context-catalog/catalog-paths.js";
+export function validateJournalFiles(value, transactionId, maxFiles, maxStoredBytes, physicalPathMode) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > maxFiles)
+        invalidJournal("journal_files_invalid");
+    const orders = new Set();
+    const paths = new Set();
+    const physicalPaths = new Set();
+    const files = [];
+    let storedBytes = 0;
+    for (const entry of value) {
+        if (!isJournalRecord(entry))
+            invalidJournal("journal_file_object_required");
+        const file = requiredJournalString(entry.path, "file.path");
+        assertJournalRelative(file, "file.path");
+        assertJournalMutationTarget(file);
+        if (physicalPathMode === "required-v3" &&
+            file !== normalizeContextPath(file))
+            invalidJournal("journal_file_logical_path_not_nfc");
+        if (paths.has(file))
+            invalidJournal("journal_file_path_duplicate");
+        paths.add(file);
+        if (physicalPathMode === "forbidden-v2" &&
+            entry.physical_path !== undefined)
+            invalidJournal("journal_v2_physical_path_forbidden");
+        if (physicalPathMode === "required-v3" && entry.physical_path === undefined)
+            invalidJournal("journal_v3_physical_path_required");
+        const physicalFile = physicalPathMode === "required-v3"
+            ? requiredJournalString(entry.physical_path, "file.physical_path")
+            : file;
+        assertJournalRelative(physicalFile, "file.physical_path");
+        assertJournalMutationTarget(physicalFile);
+        if (normalizeContextPath(physicalFile) !== normalizeContextPath(file))
+            invalidJournal("journal_file_physical_path_identity_mismatch");
+        if (physicalPaths.has(physicalFile))
+            invalidJournal("journal_file_physical_path_duplicate");
+        physicalPaths.add(physicalFile);
+        const order = requiredJournalInteger(entry.commit_order, "file.commit_order");
+        if (orders.has(order))
+            invalidJournal("journal_commit_order_duplicate");
+        orders.add(order);
+        storedBytes += validateJournalFileState(entry.before, "file.before");
+        storedBytes += validateJournalFileState(entry.after, "file.after");
+        assertSemanticIdentityShape(entry, file);
+        if (sameJournalFileState(entry.before, entry.after))
+            invalidJournal("journal_file_noop");
+        validateJournalTemporaryPath(entry.temporary_path, physicalFile, transactionId, order);
+        validateTemporaryState(entry, file);
+        validatePublishedState(entry, "before", file);
+        validatePublishedState(entry, "after", file);
+        files.push(entry);
+    }
+    if (orders.size !== files.length ||
+        [...orders].some((order) => order >= files.length))
+        invalidJournal("journal_commit_order_not_contiguous");
+    if (storedBytes > maxStoredBytes)
+        invalidJournal("journal_byte_budget_exceeded");
+    return files;
+}
+function assertSemanticIdentityShape(entry, file) {
+    if (!isJournalRecord(entry.before) || !isJournalRecord(entry.after))
+        invalidJournal(`file_state_object_required:${file}`);
+    if (entry.before.exists === true && entry.before.identity === null)
+        invalidJournal(`file_before_identity_required:${file}`);
+    if (entry.before.exists === true &&
+        isJournalRecord(entry.before.identity) &&
+        entry.before.identity.nlink !== "1")
+        invalidJournal(`file_before_hardlink_forbidden:${file}`);
+    if (entry.after.identity !== null)
+        invalidJournal(`file_after_planned_identity_forbidden:${file}`);
+}
+function validateTemporaryState(entry, file) {
+    if (entry.temporary_state === null)
+        return;
+    if (!isJournalRecord(entry.temporary_state))
+        invalidJournal(`file_temporary_state_object_required:${file}`);
+    const side = entry.temporary_state.side;
+    if (side !== "before" && side !== "after")
+        invalidJournal(`file_temporary_state_side_invalid:${file}`);
+    validateJournalRecordedFileState(entry.temporary_state.state, `file.temporary_state.state`);
+    const semantic = entry[side];
+    if (!isJournalRecord(semantic) ||
+        semantic.exists !== true ||
+        !sameJournalRecordedPayload(entry.temporary_state.state, semantic))
+        invalidJournal(`file_temporary_state_payload_mismatch:${file}`);
+    const identity = isJournalRecord(entry.temporary_state.state)
+        ? entry.temporary_state.state.identity
+        : null;
+    if (!isJournalRecord(identity) ||
+        !["1", "2"].includes(identity.nlink))
+        invalidJournal(`file_temporary_state_link_count_invalid:${file}`);
+    if (identity.nlink === "2" &&
+        isJournalRecord(entry[side === "before" ? "after" : "before"]) &&
+        entry[side === "before" ? "after" : "before"]
+            .exists !== false)
+        invalidJournal(`file_deletion_tombstone_transition_invalid:${file}`);
+}
+function validatePublishedState(entry, side, file) {
+    const field = side === "before" ? "published_before" : "published_after";
+    const value = entry[field];
+    if (value === null)
+        return;
+    validateJournalRecordedFileState(value, `file.${field}`);
+    if (!sameJournalRecordedPayload(value, entry[side]))
+        invalidJournal(`file_${field}_payload_mismatch:${file}`);
+}

package/dist/lib/context-mutation/mutation-journal-io.d.ts

@@ -0,0 +1,5 @@
+import type { ContextMutationJournal } from "./mutation-types.js";
+export declare function writeJournalTemporary(temporary: string, journal: ContextMutationJournal): Promise<void>;
+export declare function linkJournalTemporary(source: string, target: string): Promise<void>;
+export declare function unlinkJournalPath(target: string): Promise<void>;
+export declare function syncJournalDirectory(directory: string): Promise<void>;

package/dist/lib/context-mutation/mutation-journal-io.js

@@ -0,0 +1,55 @@
+import { link, open, unlink } from "node:fs/promises";
+import { setTimeout as delay } from "node:timers/promises";
+import { canonicalJson } from "../strict-codec.js";
+const WINDOWS_IO_ATTEMPTS = 32;
+export async function writeJournalTemporary(temporary, journal) {
+    const handle = await open(temporary, "wx", 0o600);
+    try {
+        await handle.writeFile(canonicalJson(journal), "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function linkJournalTemporary(source, target) {
+    await retryWindowsIo(() => link(source, target), false);
+}
+export async function unlinkJournalPath(target) {
+    await retryWindowsIo(() => unlink(target), true);
+}
+export async function syncJournalDirectory(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();
+    }
+}
+async function retryWindowsIo(operation, missingIsSuccess) {
+    const retryable = new Set(["EACCES", "EBUSY", "EPERM"]);
+    const attempts = process.platform === "win32" ? WINDOWS_IO_ATTEMPTS : 1;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        try {
+            await operation();
+            return;
+        }
+        catch (error) {
+            const code = error.code ?? "";
+            if (missingIsSuccess && code === "ENOENT")
+                return;
+            if (attempt + 1 === attempts || !retryable.has(code))
+                throw error;
+            await delay(Math.min(250, 10 * 2 ** attempt));
+        }
+    }
+}

package/dist/lib/context-mutation/mutation-journal-storage.d.ts

@@ -0,0 +1,18 @@
+import type { BigIntStats } from "node:fs";
+import type { ContextMutationJournal } from "./mutation-types.js";
+export declare const CONTEXT_MUTATION_JOURNAL_DIRECTORY = "tmp/ty-context/context-transactions";
+export interface ContextMutationJournalSnapshot {
+    absolute: string;
+    bytes: Buffer;
+    identity: BigIntStats;
+    journal: ContextMutationJournal;
+    relative: string;
+}
+export interface ContextMutationJournalReadOptions {
+    after_snapshot_read?: (absolute: string) => Promise<void>;
+}
+export declare function readLatestJournalSnapshot(repository: string, options?: ContextMutationJournalReadOptions): Promise<ContextMutationJournalSnapshot | null>;
+export declare function publishInitialJournalSnapshot(repository: string, journal: ContextMutationJournal): Promise<ContextMutationJournalSnapshot>;
+export declare function publishNextJournalSnapshot(repository: string, journal: ContextMutationJournal, expected: ContextMutationJournalSnapshot): Promise<ContextMutationJournalSnapshot>;
+export declare function removeJournalSnapshotChain(repository: string, expected: ContextMutationJournalSnapshot): Promise<void>;
+export declare function assertExpectedJournalSnapshot(current: ContextMutationJournalSnapshot | undefined, expected: ContextMutationJournalSnapshot): void;

package/dist/lib/context-mutation/mutation-journal-storage.js

@@ -0,0 +1,283 @@
+import { randomUUID } from "node:crypto";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { ensureSafeRepositoryDirectory, resolveInsideRepository, } from "../repository-path-safety.js";
+import { canonicalJson, sha256Hex } from "../strict-codec.js";
+import { linkJournalTemporary, syncJournalDirectory, unlinkJournalPath, writeJournalTemporary, } from "./mutation-journal-io.js";
+import { validateContextMutationJournal } from "./mutation-journal-validation.js";
+export const CONTEXT_MUTATION_JOURNAL_DIRECTORY = "tmp/ty-context/context-transactions";
+const SNAPSHOT_PATTERN = /^journal-(\d{6})\.json$/u;
+const TEMPORARY_PATTERN = /^\.journal-(\d{6})\.[0-9a-f-]{36}\.tmp$/u;
+const MAX_JOURNAL_SNAPSHOTS = 1024;
+const MAX_JOURNAL_BYTES = 96 * 1024 * 1024;
+export async function readLatestJournalSnapshot(repository, options = {}) {
+    const inventory = await readJournalInventory(repository);
+    const snapshots = await readSnapshotChain(inventory, options);
+    return snapshots.at(-1) ?? null;
+}
+export async function publishInitialJournalSnapshot(repository, journal) {
+    await ensureSafeRepositoryDirectory(repository, CONTEXT_MUTATION_JOURNAL_DIRECTORY, "context_mutation_journal_parent");
+    const inventory = await readJournalInventory(repository);
+    if ((await readSnapshotChain(inventory)).length)
+        invalid("unfinished_transaction_exists");
+    await removeJournalTemporaries(inventory);
+    return publishSnapshot(repository, journal);
+}
+export async function publishNextJournalSnapshot(repository, journal, expected) {
+    let inventory = await readJournalInventory(repository);
+    let current = (await readSnapshotChain(inventory)).at(-1);
+    assertExpectedJournalSnapshot(current, expected);
+    await removeJournalTemporaries(inventory);
+    inventory = await readJournalInventory(repository);
+    current = (await readSnapshotChain(inventory)).at(-1);
+    assertExpectedJournalSnapshotAfterOwnedTemporaryCleanup(current, expected);
+    return publishSnapshot(repository, journal);
+}
+export async function removeJournalSnapshotChain(repository, expected) {
+    let inventory = await readJournalInventory(repository);
+    const snapshots = await readSnapshotChain(inventory);
+    const current = snapshots.at(-1);
+    assertExpectedJournalSnapshot(current, expected);
+    await removeJournalTemporaries(inventory);
+    inventory = await readJournalInventory(repository);
+    const confirmed = await readSnapshotChain(inventory);
+    assertExpectedJournalSnapshotAfterOwnedTemporaryCleanup(confirmed.at(-1), expected);
+    for (const snapshot of [...inventory.snapshots].reverse())
+        await unlinkJournalPath(snapshot.absolute);
+    await syncJournalDirectory(inventory.directory);
+}
+async function readJournalInventory(repository) {
+    const directory = resolveInsideRepository(repository, CONTEXT_MUTATION_JOURNAL_DIRECTORY, "context_mutation_journal_parent");
+    const existing = await lstat(directory).catch((error) => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (!existing)
+        return { directory, snapshots: [], temporaries: [] };
+    await ensureSafeRepositoryDirectory(repository, CONTEXT_MUTATION_JOURNAL_DIRECTORY, "context_mutation_journal_parent");
+    const snapshots = [];
+    const temporaries = [];
+    const entries = await readdir(directory, { withFileTypes: true });
+    if (entries.length > MAX_JOURNAL_SNAPSHOTS + 16)
+        invalid("journal_entry_limit_exceeded");
+    for (const entry of entries) {
+        if (!entry.isFile())
+            invalid(`journal_entry_unsafe:${entry.name}`);
+        const snapshot = SNAPSHOT_PATTERN.exec(entry.name);
+        const temporary = TEMPORARY_PATTERN.exec(entry.name);
+        if (!snapshot && !temporary)
+            invalid(`journal_entry_unowned:${entry.name}`);
+        const absolute = path.join(directory, entry.name);
+        const status = await lstat(absolute, { bigint: true });
+        if (!status.isFile() || status.isSymbolicLink())
+            invalid(`journal_entry_unsafe:${entry.name}`);
+        if (status.ino === 0n)
+            invalid(`journal_identity_unavailable:${entry.name}`);
+        const target = snapshot ? snapshots : temporaries;
+        target.push({
+            absolute,
+            name: entry.name,
+            sequence: Number((snapshot ?? temporary)[1]),
+            status,
+        });
+    }
+    snapshots.sort((left, right) => left.sequence - right.sequence);
+    temporaries.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    if (snapshots.length > MAX_JOURNAL_SNAPSHOTS)
+        invalid("journal_snapshot_limit_exceeded");
+    return { directory, snapshots, temporaries };
+}
+async function readSnapshotChain(inventory, options = {}) {
+    for (const snapshot of inventory.snapshots)
+        assertSafeJournalLink(snapshot, inventory.temporaries);
+    for (const temporary of inventory.temporaries)
+        assertSafeJournalTemporary(temporary, inventory.snapshots);
+    const snapshots = [];
+    for (const entry of inventory.snapshots) {
+        if (entry.status.size > BigInt(MAX_JOURNAL_BYTES))
+            invalid("journal_snapshot_too_large");
+        const bytes = await readFile(entry.absolute);
+        await options.after_snapshot_read?.(entry.absolute);
+        const afterRead = await lstat(entry.absolute, { bigint: true }).catch((error) => {
+            if (error.code === "ENOENT")
+                invalid(`journal_changed_during_read:${entry.name}`);
+            throw error;
+        });
+        if (!sameJournalIdentity(entry.status, afterRead))
+            invalid(`journal_changed_during_read:${entry.name}`);
+        let value;
+        try {
+            value = JSON.parse(bytes.toString("utf8"));
+        }
+        catch (error) {
+            invalid(`journal_unreadable:${message(error)}`);
+        }
+        const journal = validateContextMutationJournal(value);
+        if (journal.journal_sequence !== entry.sequence)
+            invalid("journal_filename_sequence_mismatch");
+        if (!bytes.equals(Buffer.from(canonicalJson(journal), "utf8")))
+            invalid("journal_noncanonical_bytes");
+        const previous = snapshots.at(-1);
+        if (previous) {
+            if (journal.journal_sequence !== previous.journal.journal_sequence + 1)
+                invalid("journal_sequence_gap");
+            if (journal.transaction_id !== previous.journal.transaction_id)
+                invalid("journal_transaction_changed");
+            if (journal.previous_journal_sha256 !== sha256Hex(previous.bytes))
+                invalid("journal_predecessor_mismatch");
+        }
+        snapshots.push({
+            absolute: entry.absolute,
+            bytes,
+            identity: afterRead,
+            journal,
+            relative: `${CONTEXT_MUTATION_JOURNAL_DIRECTORY}/${entry.name}`,
+        });
+    }
+    return snapshots;
+}
+async function publishSnapshot(repository, journal) {
+    validateContextMutationJournal(journal);
+    const directory = resolveInsideRepository(repository, CONTEXT_MUTATION_JOURNAL_DIRECTORY, "context_mutation_journal_parent");
+    const sequence = String(journal.journal_sequence).padStart(6, "0");
+    const finalPath = path.join(directory, `journal-${sequence}.json`);
+    const temporary = path.join(directory, `.journal-${sequence}.${randomUUID()}.tmp`);
+    await writeJournalTemporary(temporary, journal);
+    let published = false;
+    try {
+        await linkJournalTemporary(temporary, finalPath);
+        published = true;
+        await unlinkJournalPath(temporary);
+        await syncJournalDirectory(directory);
+        await removeSupersededSnapshots(repository, journal.journal_sequence);
+        await syncJournalDirectory(directory);
+        const publishedSnapshot = await readLatestJournalSnapshot(repository);
+        if (!publishedSnapshot ||
+            publishedSnapshot.journal.journal_sequence !== journal.journal_sequence ||
+            !publishedSnapshot.bytes.equals(Buffer.from(canonicalJson(journal), "utf8")))
+            invalid("journal_publication_readback_mismatch");
+        return publishedSnapshot;
+    }
+    catch (error) {
+        if (!published)
+            await unlinkJournalPath(temporary).catch(() => undefined);
+        if (error.code === "EEXIST")
+            invalid("journal_compare_and_swap_failed");
+        throw error;
+    }
+}
+export function assertExpectedJournalSnapshot(current, expected) {
+    if (!current)
+        invalid("journal_missing");
+    if (current.relative !== expected.relative ||
+        !current.bytes.equals(expected.bytes) ||
+        !sameJournalIdentity(current.identity, expected.identity))
+        invalid("journal_compare_and_swap_failed");
+}
+function assertExpectedJournalSnapshotAfterOwnedTemporaryCleanup(current, expected) {
+    if (!current)
+        invalid("journal_missing");
+    if (current.relative === expected.relative &&
+        current.bytes.equals(expected.bytes) &&
+        (sameJournalIdentity(current.identity, expected.identity) ||
+            (expected.identity.nlink === 2n &&
+                current.identity.nlink === 1n &&
+                sameStableJournalIdentity(current.identity, expected.identity))))
+        return;
+    invalid("journal_compare_and_swap_failed");
+}
+function assertSafeJournalLink(snapshot, temporaries) {
+    if (snapshot.status.nlink === 1n)
+        return;
+    const ownedLinks = temporaries.filter((entry) => entry.sequence === snapshot.sequence &&
+        entry.status.dev === snapshot.status.dev &&
+        entry.status.ino === snapshot.status.ino &&
+        sameJournalIdentity(entry.status, snapshot.status));
+    if (snapshot.status.nlink !== 2n || ownedLinks.length !== 1)
+        invalid(`journal_hardlink_unowned_manual_recovery_required:${snapshot.name}`);
+}
+function assertSafeJournalTemporary(temporary, snapshots) {
+    const ownedSnapshots = snapshots.filter((entry) => entry.sequence === temporary.sequence &&
+        entry.status.dev === temporary.status.dev &&
+        entry.status.ino === temporary.status.ino &&
+        entry.status.nlink === 2n &&
+        temporary.status.nlink === 2n &&
+        sameJournalIdentity(entry.status, temporary.status));
+    if (ownedSnapshots.length !== 1)
+        invalid(`journal_temporary_unowned_manual_recovery_required:${temporary.name}`);
+}
+function sameJournalIdentity(left, right) {
+    return (sameStableJournalIdentity(left, right) &&
+        left.nlink === right.nlink &&
+        left.ctimeNs === right.ctimeNs);
+}
+function sameStableJournalIdentity(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.size === right.size &&
+        left.mode === right.mode &&
+        left.mtimeNs === right.mtimeNs);
+}
+async function removeJournalTemporaries(inventory) {
+    if (inventory.temporaries.length === 0)
+        return;
+    const claimedSnapshots = new Set();
+    for (const temporary of inventory.temporaries) {
+        const candidates = inventory.snapshots.filter((snapshot) => snapshot.sequence === temporary.sequence &&
+            snapshot.status.dev === temporary.status.dev &&
+            snapshot.status.ino === temporary.status.ino);
+        const snapshot = candidates.length === 1 ? candidates[0] : undefined;
+        if (!snapshot ||
+            claimedSnapshots.has(snapshot.name) ||
+            snapshot.status.nlink !== 2n ||
+            temporary.status.nlink !== 2n ||
+            !sameJournalIdentity(snapshot.status, temporary.status))
+            invalid(`journal_temporary_unowned_manual_recovery_required:${temporary.name}`);
+        claimedSnapshots.add(snapshot.name);
+        const [currentSnapshot, currentTemporary] = await Promise.all([
+            lstatOwnedJournalEntry(snapshot),
+            lstatOwnedJournalEntry(temporary),
+        ]);
+        if (!sameJournalIdentity(snapshot.status, currentSnapshot) ||
+            !sameJournalIdentity(temporary.status, currentTemporary) ||
+            !sameJournalIdentity(currentSnapshot, currentTemporary))
+            invalid(`journal_temporary_identity_changed_manual_recovery_required:${temporary.name}`);
+        try {
+            await unlinkJournalPath(temporary.absolute);
+        }
+        catch (error) {
+            invalid(`journal_temporary_cleanup_failed_manual_recovery_required:${temporary.name}:${message(error)}`);
+        }
+        const afterSnapshot = await lstatOwnedJournalEntry(snapshot);
+        const remainingTemporary = await lstat(temporary.absolute, {
+            bigint: true,
+        }).catch((error) => {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
+        });
+        if (remainingTemporary ||
+            afterSnapshot.nlink !== 1n ||
+            !sameStableJournalIdentity(currentSnapshot, afterSnapshot))
+            invalid(`journal_temporary_cleanup_transition_invalid_manual_recovery_required:${temporary.name}`);
+    }
+    await syncJournalDirectory(inventory.directory);
+}
+async function lstatOwnedJournalEntry(entry) {
+    return lstat(entry.absolute, { bigint: true }).catch((error) => {
+        invalid(`journal_temporary_identity_changed_manual_recovery_required:${entry.name}:${message(error)}`);
+    });
+}
+async function removeSupersededSnapshots(repository, currentSequence) {
+    const inventory = await readJournalInventory(repository);
+    for (const snapshot of inventory.snapshots)
+        if (snapshot.sequence < currentSequence)
+            await unlinkJournalPath(snapshot.absolute);
+}
+function invalid(reason) {
+    throw new Error(`context_mutation_invalid:${reason}`);
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lib/context-mutation/mutation-journal-validation-support.d.ts

@@ -0,0 +1,16 @@
+export declare function validateJournalFileState(value: unknown, label: string): number;
+export declare function validateJournalRecordedFileState(value: unknown, label: string): void;
+export declare function sameJournalRecordedPayload(recorded: unknown, semantic: unknown): boolean;
+export declare function sameJournalFileState(left: unknown, right: unknown): boolean;
+export declare function isPresentJournalState(value: unknown): boolean;
+export declare function isAbsentJournalState(value: unknown): boolean;
+export declare function validateJournalTemporaryPath(value: unknown, file: string, transactionId: string, order: number): void;
+export declare function assertJournalMutationTarget(value: string): void;
+export declare function assertJournalContextMarkdownPath(value: string, label: string): void;
+export declare function assertJournalRelative(value: string, label: string): void;
+export declare function validateJournalDigest(value: unknown, label: string): string;
+export declare function requiredJournalString(value: unknown, label: string): string;
+export declare function requiredJournalInteger(value: unknown, label: string): number;
+export declare function isJournalRecord(value: unknown): value is Record<string, unknown>;
+export declare function invalidJournal(reason: string): never;
+export declare function validateIdentity(value: unknown, label: string): void;