project-tiny-context-harness 0.8.17 → 0.11.0

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;

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

@@ -0,0 +1,140 @@
+import path from "node:path";
+import { sha256Hex } from "../strict-codec.js";
+export function validateJournalFileState(value, label) {
+    if (!isJournalRecord(value))
+        invalidJournal(`${label}_object_required`);
+    assertExactFields(value, ["exists", "sha256", "bytes_base64", "mode", "identity"], label);
+    if (typeof value.exists !== "boolean")
+        invalidJournal(`${label}_exists_invalid`);
+    if (!value.exists) {
+        if (value.sha256 !== null ||
+            value.bytes_base64 !== null ||
+            value.mode !== null ||
+            value.identity !== null)
+            invalidJournal(`${label}_absent_shape`);
+        return 0;
+    }
+    const digest = validateJournalDigest(value.sha256, `${label}.sha256`);
+    if (typeof value.bytes_base64 !== "string")
+        invalidJournal(`${label}.bytes_base64_string_required`);
+    const bytes = Buffer.from(value.bytes_base64, "base64");
+    if (bytes.toString("base64") !== value.bytes_base64)
+        invalidJournal(`${label}_base64_invalid`);
+    if (sha256Hex(bytes) !== digest)
+        invalidJournal(`${label}_digest_mismatch`);
+    const mode = requiredJournalInteger(value.mode, `${label}.mode`);
+    if (mode > 0o777)
+        invalidJournal(`${label}_mode_invalid`);
+    if (value.identity !== null)
+        validateIdentity(value.identity, label);
+    return bytes.length;
+}
+export function validateJournalRecordedFileState(value, label) {
+    if (!isJournalRecord(value))
+        invalidJournal(`${label}_object_required`);
+    assertExactFields(value, ["exists", "sha256", "mode", "identity"], label);
+    if (typeof value.exists !== "boolean")
+        invalidJournal(`${label}_exists_invalid`);
+    if (!value.exists) {
+        if (value.sha256 !== null || value.mode !== null || value.identity !== null)
+            invalidJournal(`${label}_absent_shape`);
+        return;
+    }
+    validateJournalDigest(value.sha256, `${label}.sha256`);
+    const mode = requiredJournalInteger(value.mode, `${label}.mode`);
+    if (mode > 0o777)
+        invalidJournal(`${label}_mode_invalid`);
+    if (value.identity === null)
+        invalidJournal(`${label}_identity_required`);
+    validateIdentity(value.identity, label);
+}
+export function sameJournalRecordedPayload(recorded, semantic) {
+    if (!isJournalRecord(recorded) || !isJournalRecord(semantic))
+        return false;
+    return (recorded.exists === semantic.exists &&
+        recorded.sha256 === semantic.sha256 &&
+        recorded.mode === semantic.mode);
+}
+export function sameJournalFileState(left, right) {
+    if (!isJournalRecord(left) || !isJournalRecord(right))
+        return false;
+    return (left.exists === right.exists &&
+        left.sha256 === right.sha256 &&
+        left.mode === right.mode);
+}
+export function isPresentJournalState(value) {
+    return isJournalRecord(value) && value.exists === true;
+}
+export function isAbsentJournalState(value) {
+    return isJournalRecord(value) && value.exists === false;
+}
+export function validateJournalTemporaryPath(value, file, transactionId, order) {
+    const temporary = requiredJournalString(value, "file.temporary_path");
+    assertJournalRelative(temporary, "file.temporary_path");
+    const expected = `${path.posix.dirname(file)}/.${path.posix.basename(file)}.ty-context-mutation-${transactionId.slice(0, 16)}-${order}.tmp`;
+    if (temporary !== expected)
+        invalidJournal("temporary_path_unowned");
+}
+export function assertJournalMutationTarget(value) {
+    if (value === "project_context/context.toml")
+        return;
+    assertJournalContextMarkdownPath(value, "mutation_target");
+}
+export function assertJournalContextMarkdownPath(value, label) {
+    assertJournalRelative(value, label);
+    if (!value.startsWith("project_context/") || !value.endsWith(".md"))
+        invalidJournal(`${label}_context_markdown_required`);
+}
+export function assertJournalRelative(value, label) {
+    const normalized = value.replace(/\\/gu, "/");
+    const segments = normalized.split("/");
+    if (value !== normalized ||
+        !normalized ||
+        path.isAbsolute(value) ||
+        normalized.startsWith("/") ||
+        segments.some((segment) => !segment || segment === "." || segment === ".."))
+        invalidJournal(`${label}_unsafe`);
+}
+export function validateJournalDigest(value, label) {
+    const digest = requiredJournalString(value, label);
+    if (!/^[0-9a-f]{64}$/u.test(digest))
+        invalidJournal(`${label}_invalid`);
+    return digest;
+}
+export function requiredJournalString(value, label) {
+    if (typeof value !== "string" || value.length === 0)
+        invalidJournal(`${label}_string_required`);
+    return value;
+}
+export function requiredJournalInteger(value, label) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+        invalidJournal(`${label}_integer_required`);
+    return value;
+}
+export function isJournalRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+export function invalidJournal(reason) {
+    throw new Error(`context_mutation_invalid:${reason}`);
+}
+export function validateIdentity(value, label) {
+    if (!isJournalRecord(value))
+        invalidJournal(`${label}_identity_invalid`);
+    const fields = ["dev", "ino", "nlink", "size", "mtime_ns", "ctime_ns"];
+    if (Object.keys(value).sort().join("\0") !== [...fields].sort().join("\0"))
+        invalidJournal(`${label}_identity_fields_invalid`);
+    for (const field of ["dev", "ino", "nlink", "size"]) {
+        const item = value[field];
+        if (typeof item !== "string" || !/^(?:0|[1-9][0-9]*)$/u.test(item))
+            invalidJournal(`${label}.identity.${field}_decimal_required`);
+    }
+    for (const field of ["mtime_ns", "ctime_ns"]) {
+        const item = value[field];
+        if (typeof item !== "string" || !/^(?:0|-?[1-9][0-9]*)$/u.test(item))
+            invalidJournal(`${label}.identity.${field}_decimal_required`);
+    }
+}
+function assertExactFields(value, fields, label) {
+    if (Object.keys(value).sort().join("\0") !== [...fields].sort().join("\0"))
+        invalidJournal(`${label}_fields_invalid`);
+}

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

@@ -0,0 +1,3 @@
+import type { ContextMutationJournal } from "./mutation-types.js";
+export declare const CONTEXT_MUTATION_JOURNAL_SCHEMA: "context-mutation-journal-v3";
+export declare function validateContextMutationJournal(value: unknown): ContextMutationJournal;

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

@@ -0,0 +1,177 @@
+import { normalizeContextRole } from "../context-catalog/catalog-portable-contract.js";
+import { validateJournalFiles } from "./mutation-journal-file-validation.js";
+import { assertJournalContextMarkdownPath, assertJournalRelative, invalidJournal, isAbsentJournalState, isJournalRecord, isPresentJournalState, requiredJournalInteger, requiredJournalString, validateJournalDigest, } from "./mutation-journal-validation-support.js";
+export const CONTEXT_MUTATION_JOURNAL_SCHEMA = "context-mutation-journal-v3";
+const LEGACY_CONTEXT_MUTATION_JOURNAL_SCHEMA = "context-mutation-journal-v2";
+const MAX_MUTATION_FILES = 512;
+const MAX_MUTATION_DIRECTORIES = 64;
+const MAX_STORED_BYTES = 64 * 1024 * 1024;
+const MAX_JOURNAL_SEQUENCE = 4095;
+export function validateContextMutationJournal(value) {
+    if (!isJournalRecord(value))
+        invalidJournal("journal_object_required");
+    if (typeof value.schema_version === "string" &&
+        /^context-mutation-journal-v(?:0|1)$/u.test(value.schema_version))
+        invalidJournal("journal_pre_v2_manual_recovery_required:use_the_ty-context_version_that_created_the_journal_or_restore_exact_files_from_version_control");
+    if (value.schema_version !== CONTEXT_MUTATION_JOURNAL_SCHEMA &&
+        value.schema_version !== LEGACY_CONTEXT_MUTATION_JOURNAL_SCHEMA)
+        invalidJournal("journal_schema_unsupported");
+    const transactionId = requiredJournalString(value.transaction_id, "transaction_id");
+    if (!/^[0-9a-f]{64}$/u.test(transactionId))
+        invalidJournal("transaction_id_invalid");
+    const journalSequence = requiredJournalInteger(value.journal_sequence, "journal_sequence");
+    if (journalSequence > MAX_JOURNAL_SEQUENCE)
+        invalidJournal("journal_sequence_exceeded");
+    if (journalSequence === 0) {
+        if (value.previous_journal_sha256 !== null)
+            invalidJournal("initial_journal_predecessor_forbidden");
+    }
+    else {
+        validateJournalDigest(value.previous_journal_sha256, "previous_journal_sha256");
+    }
+    const operation = value.operation;
+    if (operation !== "register" && operation !== "move")
+        invalidJournal("operation_invalid");
+    const state = value.state;
+    if (state !== "planning" &&
+        state !== "prepared" &&
+        state !== "committing" &&
+        state !== "validating")
+        invalidJournal("journal_state_invalid");
+    const files = validateJournalFiles(value.files, transactionId, MAX_MUTATION_FILES, MAX_STORED_BYTES, value.schema_version === CONTEXT_MUTATION_JOURNAL_SCHEMA
+        ? "required-v3"
+        : "forbidden-v2");
+    const directories = validateDirectories(value.directories, operation);
+    validateAppliedPaths(value.applied_paths, files, state);
+    validateJournalDigest(value.catalog_before_identity, "catalog_before_identity");
+    validateJournalDigest(value.catalog_after_identity, "catalog_after_identity");
+    if (!isJournalRecord(value.operation_data))
+        invalidJournal("operation_data_invalid");
+    if (value.operation_data.kind !== operation)
+        invalidJournal("operation_data_kind_mismatch");
+    validateOperationData(value.operation_data, operation);
+    if (operation === "register" &&
+        (files.length !== 1 || files[0].path !== "project_context/context.toml"))
+        invalidJournal("register_file_set_invalid");
+    if (operation === "move")
+        validateMoveFileSet(files, value.operation_data, directories);
+    return value;
+}
+function validateDirectories(value, operation) {
+    if (!Array.isArray(value) || value.length > MAX_MUTATION_DIRECTORIES)
+        invalidJournal("journal_directories_invalid");
+    if (operation === "register" && value.length !== 0)
+        invalidJournal("register_directories_forbidden");
+    const seen = new Set();
+    const directories = [];
+    let previousDepth = 0;
+    for (const entry of value) {
+        if (!isJournalRecord(entry))
+            invalidJournal("journal_directory_object_required");
+        const directory = requiredJournalString(entry.path, "directory.path");
+        assertJournalRelative(directory, "directory.path");
+        if (!directory.startsWith("project_context/"))
+            invalidJournal("journal_directory_context_required");
+        if (entry.before_exists !== false)
+            invalidJournal("journal_directory_before_state_invalid");
+        if (seen.has(directory))
+            invalidJournal("journal_directory_duplicate");
+        seen.add(directory);
+        directories.push(directory);
+        const depth = directory.split("/").length;
+        if (depth < previousDepth)
+            invalidJournal("journal_directory_order_invalid");
+        previousDepth = depth;
+    }
+    return directories;
+}
+function validateMoveFileSet(files, operationData, directories) {
+    if (files.length < 3)
+        invalidJournal("move_file_set_incomplete");
+    const ordered = [...files].sort((left, right) => left.commit_order - right.commit_order);
+    const from = operationData.from_path;
+    const to = operationData.to_path;
+    if (ordered[0].path !== to ||
+        !isAbsentJournalState(ordered[0].before) ||
+        !isPresentJournalState(ordered[0].after))
+        invalidJournal("move_target_change_invalid");
+    const source = ordered.at(-1);
+    if (source.path !== from ||
+        !isPresentJournalState(source.before) ||
+        !isAbsentJournalState(source.after))
+        invalidJournal("move_source_change_invalid");
+    const manifest = ordered.at(-2);
+    if (manifest.path !== "project_context/context.toml" ||
+        !isPresentJournalState(manifest.before) ||
+        !isPresentJournalState(manifest.after))
+        invalidJournal("move_manifest_change_invalid");
+    for (const reference of ordered.slice(1, -2))
+        if (!isPresentJournalState(reference.before) ||
+            !isPresentJournalState(reference.after))
+            invalidJournal("move_reference_change_invalid");
+    for (const directory of directories)
+        if (!to.startsWith(`${directory}/`))
+            invalidJournal("move_directory_not_target_ancestor");
+    for (let index = 1; index < directories.length; index += 1)
+        if (!directories[index].startsWith(`${directories[index - 1]}/`))
+            invalidJournal("move_directories_not_chain");
+}
+function validateAppliedPaths(value, files, state) {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string"))
+        invalidJournal("journal_applied_paths_invalid");
+    const ordered = [...files]
+        .sort((left, right) => left.commit_order - right.commit_order)
+        .map((entry) => entry.path);
+    if (value.some((entry, index) => entry !== ordered[index]) ||
+        new Set(value).size !== value.length)
+        invalidJournal("journal_applied_paths_not_prefix");
+    if ((state === "planning" || state === "prepared") && value.length !== 0)
+        invalidJournal("journal_applied_paths_state_mismatch");
+    if (state === "validating" && value.length !== ordered.length)
+        invalidJournal("journal_applied_paths_state_mismatch");
+    for (const file of files) {
+        const applied = value.includes(file.path);
+        if (applied && file.published_after === null)
+            invalidJournal("journal_applied_path_endpoint_missing");
+        if ((state === "planning" || state === "prepared") &&
+            (file.published_before !== null || file.published_after !== null))
+            invalidJournal("journal_published_state_phase_mismatch");
+    }
+}
+function validateOperationData(value, operation) {
+    const paths = value.expected_default_paths;
+    if (!Array.isArray(paths) || paths.some((entry) => typeof entry !== "string"))
+        invalidJournal("operation_default_paths_invalid");
+    const unique = new Set();
+    for (const file of paths) {
+        assertJournalRelative(file, "default_path");
+        if (unique.has(file))
+            invalidJournal("operation_default_path_duplicate");
+        unique.add(file);
+    }
+    requiredJournalInteger(value.expected_default_bytes, "expected_default_bytes");
+    if (operation === "register") {
+        const contextPath = requiredJournalString(value.context_path, "context_path");
+        assertJournalContextMarkdownPath(contextPath, "context_path");
+        if (typeof value.role !== "string" || !normalizeContextRole(value.role))
+            invalidJournal("operation_role_invalid");
+        if (value.read_policy !== "default" && value.read_policy !== "on-demand")
+            invalidJournal("operation_read_policy_invalid");
+        return;
+    }
+    const from = requiredJournalString(value.from_path, "from_path");
+    const to = requiredJournalString(value.to_path, "to_path");
+    assertJournalContextMarkdownPath(from, "from_path");
+    assertJournalContextMarkdownPath(to, "to_path");
+    if (from === to)
+        invalidJournal("operation_move_same_path");
+    if (value.owner_source !== "area" && value.owner_source !== "context")
+        invalidJournal("operation_owner_source_invalid");
+    if (typeof value.role !== "string" || !normalizeContextRole(value.role))
+        invalidJournal("operation_role_invalid");
+    if (value.read_policy !== null && typeof value.read_policy !== "string")
+        invalidJournal("operation_read_policy_invalid");
+    if (!Array.isArray(value.expected_reference_issues) ||
+        value.expected_reference_issues.some((entry) => typeof entry !== "string"))
+        invalidJournal("operation_reference_issues_invalid");
+}

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

@@ -0,0 +1,8 @@
+export { CONTEXT_MUTATION_JOURNAL_DIRECTORY } from "./mutation-journal-storage.js";
+import type { ContextMutationJournal, ContextMutationJournalState, ContextMutationPlan } from "./mutation-types.js";
+export declare function readContextMutationJournal(repository: string): Promise<ContextMutationJournal | null>;
+export declare function assertNoUnfinishedContextMutationForAuthority(repository: string): Promise<void>;
+export declare function createContextMutationJournal(repository: string, plan: ContextMutationPlan): Promise<ContextMutationJournal>;
+export declare function updateContextMutationJournal(repository: string, expected: ContextMutationJournal, successor: ContextMutationJournal, expectedStates: ContextMutationJournalState[]): Promise<ContextMutationJournal>;
+export declare function removeContextMutationJournal(repository: string, expected: ContextMutationJournal): Promise<void>;
+export declare function assertSameContextMutationJournalSnapshot(expected: ContextMutationJournal, current: ContextMutationJournal): void;