project-tiny-context-harness 0.8.16 → 0.11.0

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 { contextMutationAffectedPaths, withContextMutationAuthorityInterlock, } from "./mutation-long-task-guard.js";
+import { validateLiveContextMutation } from "./mutation-live-validation.js";
+export async function executeContextMutationPlan(repository, plan, options = {}) {
+    await withContextMutationAuthorityInterlock(repository, contextMutationAffectedPaths(plan), 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;

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