project-tiny-context-harness 0.8.16 → 0.11.0

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

@@ -0,0 +1,111 @@
+import { canonicalJson, sha256Hex } from "../strict-codec.js";
+import { publishInitialJournalSnapshot, publishNextJournalSnapshot, readLatestJournalSnapshot, removeJournalSnapshotChain, assertExpectedJournalSnapshot, } from "./mutation-journal-storage.js";
+export { CONTEXT_MUTATION_JOURNAL_DIRECTORY } from "./mutation-journal-storage.js";
+import { CONTEXT_MUTATION_JOURNAL_SCHEMA, validateContextMutationJournal, } from "./mutation-journal-validation.js";
+const journalSnapshotBindings = new WeakMap();
+export async function readContextMutationJournal(repository) {
+    const snapshot = await readLatestJournalSnapshot(repository);
+    return snapshot ? bindJournalSnapshot(snapshot) : null;
+}
+export async function assertNoUnfinishedContextMutationForAuthority(repository) {
+    const journal = await readContextMutationJournal(repository);
+    if (journal)
+        throw new Error(`active_authority_context_mutation_unfinished:${journal.transaction_id}`);
+}
+export async function createContextMutationJournal(repository, plan) {
+    const journal = {
+        schema_version: CONTEXT_MUTATION_JOURNAL_SCHEMA,
+        ...plan,
+        journal_sequence: 0,
+        previous_journal_sha256: null,
+        state: "planning",
+        applied_paths: [],
+    };
+    validateContextMutationJournal(journal);
+    return bindJournalSnapshot(await publishInitialJournalSnapshot(repository, journal));
+}
+export async function updateContextMutationJournal(repository, expected, successor, expectedStates) {
+    validateContextMutationJournal(expected);
+    validateContextMutationJournal(successor);
+    if (canonicalJson(immutableMutationPlan(expected)) !==
+        canonicalJson(immutableMutationPlan(successor)))
+        invalid("journal_successor_plan_changed");
+    const current = await readLatestJournalSnapshot(repository);
+    if (!current)
+        invalid("journal_missing");
+    try {
+        assertExpectedJournalSnapshot(current, requiredSnapshotBinding(expected));
+    }
+    catch (error) {
+        if (/journal_compare_and_swap_failed$/u.test(message(error)))
+            invalid("journal_predecessor_compare_and_swap_failed");
+        throw error;
+    }
+    if (current.journal.transaction_id !== expected.transaction_id)
+        invalid("journal_transaction_changed");
+    const expectedBytes = Buffer.from(canonicalJson(expected), "utf8");
+    if (current.journal.journal_sequence !== expected.journal_sequence ||
+        sha256Hex(current.bytes) !== sha256Hex(expectedBytes))
+        invalid("journal_predecessor_compare_and_swap_failed");
+    if (!expectedStates.includes(current.journal.state))
+        invalid(`journal_state_changed:${current.journal.state}`);
+    const next = {
+        ...successor,
+        journal_sequence: expected.journal_sequence + 1,
+        previous_journal_sha256: sha256Hex(current.bytes),
+    };
+    validateContextMutationJournal(next);
+    return bindJournalSnapshot(await publishNextJournalSnapshot(repository, next, current));
+}
+function immutableMutationPlan(journal) {
+    return {
+        transaction_id: journal.transaction_id,
+        operation: journal.operation,
+        catalog_before_identity: journal.catalog_before_identity,
+        catalog_after_identity: journal.catalog_after_identity,
+        directories: journal.directories,
+        files: journal.files.map((file) => ({
+            path: file.path,
+            physical_path: file.physical_path,
+            before: file.before,
+            after: file.after,
+            commit_order: file.commit_order,
+            temporary_path: file.temporary_path,
+        })),
+        operation_data: journal.operation_data,
+    };
+}
+export async function removeContextMutationJournal(repository, expected) {
+    validateContextMutationJournal(expected);
+    const current = await readLatestJournalSnapshot(repository);
+    if (!current)
+        invalid("journal_missing");
+    const expectedSnapshot = requiredSnapshotBinding(expected);
+    assertExpectedJournalSnapshot(current, expectedSnapshot);
+    if (current.journal.journal_sequence !== expected.journal_sequence ||
+        sha256Hex(current.bytes) !==
+            sha256Hex(Buffer.from(canonicalJson(expected), "utf8")))
+        invalid("journal_terminal_compare_and_swap_failed");
+    await removeJournalSnapshotChain(repository, current);
+}
+export function assertSameContextMutationJournalSnapshot(expected, current) {
+    const expectedSnapshot = requiredSnapshotBinding(expected);
+    const currentSnapshot = requiredSnapshotBinding(current);
+    assertExpectedJournalSnapshot(currentSnapshot, expectedSnapshot);
+}
+function bindJournalSnapshot(snapshot) {
+    journalSnapshotBindings.set(snapshot.journal, snapshot);
+    return snapshot.journal;
+}
+function requiredSnapshotBinding(journal) {
+    const snapshot = journalSnapshotBindings.get(journal);
+    if (!snapshot)
+        invalid("journal_predecessor_identity_missing");
+    return snapshot;
+}
+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-live-validation.d.ts

@@ -0,0 +1,3 @@
+import type { ContextMutationJournal } from "./mutation-types.js";
+export declare function validateLiveContextMutation(repository: string, journal: ContextMutationJournal): Promise<void>;
+export declare function validateRolledBackContextMutation(repository: string, journal: ContextMutationJournal): Promise<void>;

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

@@ -0,0 +1,51 @@
+import { readFile } from "node:fs/promises";
+import { loadContextCatalog } from "../context-catalog/catalog-load.js";
+import { catalogErrors } from "../context-catalog/catalog-diagnostics.js";
+import { resolveCatalogFile } from "../context-catalog/catalog-paths.js";
+import { assertProtectedRepositoryFile } from "../repository-path-safety.js";
+import { validateContextContentForRole } from "../validators.js";
+import { validateLiveContextMove } from "../context-move/context-move-live-validation.js";
+import { contextCatalogIdentity, contextFootprintState, } from "./mutation-staged-fs.js";
+export async function validateLiveContextMutation(repository, journal) {
+    const catalog = await loadContextCatalog(repository);
+    const errors = catalogErrors(catalog.diagnostics);
+    if (errors.length)
+        invalid(`live_catalog:${errors.join("|")}`);
+    if (contextCatalogIdentity(catalog) !== journal.catalog_after_identity)
+        invalid("live_catalog_identity_mismatch");
+    const footprint = contextFootprintState(catalog);
+    if (footprint.bytes !== journal.operation_data.expected_default_bytes ||
+        !sameArray(footprint.paths, journal.operation_data.expected_default_paths))
+        invalid("live_default_footprint_mismatch");
+    if (journal.operation_data.kind === "register") {
+        const data = journal.operation_data;
+        const registered = catalog.registered_contexts.filter((entry) => entry.path === data.context_path && entry.source === "context");
+        if (registered.length !== 1)
+            invalid("live_registration_missing");
+        if (registered[0].role !== data.role ||
+            registered[0].read_policy !== data.read_policy)
+            invalid("live_registration_metadata_mismatch");
+        const file = resolveCatalogFile(catalog, data.context_path);
+        if (!file)
+            invalid("live_registration_file_missing");
+        const absolute = await assertProtectedRepositoryFile(repository, file.absolute_path, "context_mutation_registered_context");
+        const content = await readFile(absolute, "utf8");
+        const recoveryErrors = validateContextContentForRole(repository, data.context_path, content, data.role);
+        if (recoveryErrors.length)
+            invalid(`live_context_recovery:${recoveryErrors.join("|")}`);
+        return;
+    }
+    await validateLiveContextMove(repository, catalog, journal);
+}
+export async function validateRolledBackContextMutation(repository, journal) {
+    const catalog = await loadContextCatalog(repository);
+    if (contextCatalogIdentity(catalog) !== journal.catalog_before_identity)
+        invalid("rollback_catalog_identity_mismatch");
+}
+function sameArray(left, right) {
+    return (left.length === right.length &&
+        left.every((value, index) => value === right[index]));
+}
+function invalid(reason) {
+    throw new Error(`context_mutation_invalid:${reason}`);
+}

package/dist/lib/context-mutation/mutation-long-task-guard.d.ts

@@ -0,0 +1,6 @@
+import type { ContextMutationJournal, ContextMutationPlan } from "./mutation-types.js";
+type ContextMutationAuthorityConflictPhase = "start" | "recovery";
+export declare function assertContextMutationOutsideActiveLongTask(repository: string, affectedPaths: Iterable<string>): Promise<void>;
+export declare function withContextMutationAuthorityInterlock<T>(repository: string, affectedPaths: Iterable<string>, action: () => Promise<T>, conflictPhase?: ContextMutationAuthorityConflictPhase): Promise<T>;
+export declare function contextMutationAffectedPaths(mutation: ContextMutationPlan | ContextMutationJournal): string[];
+export {};

package/dist/lib/context-mutation/mutation-long-task-guard.js

@@ -0,0 +1,57 @@
+import { CLI_EXIT_CODES, CliCommandError } from "../cli-exit.js";
+import { repositoryRoot } from "../long-task-git.js";
+import { readActiveLongTaskBinding, withActiveAuthorityLock, } from "../long-task-state.js";
+export async function assertContextMutationOutsideActiveLongTask(repository, affectedPaths) {
+    const gitRepository = await contextMutationGitRepository(repository);
+    if (!gitRepository)
+        return;
+    await assertPathsOutsideActiveLongTask(gitRepository, affectedPaths);
+}
+export async function withContextMutationAuthorityInterlock(repository, affectedPaths, action, conflictPhase = "start") {
+    const gitRepository = await contextMutationGitRepository(repository);
+    if (!gitRepository)
+        return action();
+    return withActiveAuthorityLock(gitRepository, "context_mutation", async () => {
+        await assertPathsOutsideActiveLongTask(gitRepository, affectedPaths, conflictPhase);
+        return action();
+    });
+}
+export function contextMutationAffectedPaths(mutation) {
+    const paths = new Set(mutation.files.map((entry) => entry.path));
+    if (mutation.operation_data.kind === "register")
+        paths.add(mutation.operation_data.context_path);
+    else {
+        paths.add(mutation.operation_data.from_path);
+        paths.add(mutation.operation_data.to_path);
+    }
+    return [...paths].sort((left, right) => Buffer.from(left, "utf8").compare(Buffer.from(right, "utf8")));
+}
+async function contextMutationGitRepository(repository) {
+    return repositoryRoot(repository).catch((error) => {
+        if (/(?:not a git repository|--local can only be used inside a git repository)/iu.test(message(error)))
+            return null;
+        throw new CliCommandError(CLI_EXIT_CODES.catalog, `context mutation cannot establish Long-Task Authority state: ${message(error)}`, { cause: error });
+    });
+}
+async function assertPathsOutsideActiveLongTask(gitRepository, affectedPaths, conflictPhase = "start") {
+    const active = await readActiveLongTaskBinding(gitRepository).catch((error) => {
+        throw new CliCommandError(CLI_EXIT_CODES.catalog, `context mutation cannot establish Long-Task Authority state: ${message(error)}`, { cause: error });
+    });
+    if (!active)
+        return;
+    const bound = new Set([
+        ...active.authority_snapshot.context_snapshot.files,
+        ...Object.keys(active.authority_snapshot.source_hashes),
+    ]);
+    const conflicts = [...affectedPaths]
+        .filter((file) => bound.has(file))
+        .sort((left, right) => Buffer.from(left, "utf8").compare(Buffer.from(right, "utf8")));
+    if (conflicts.length === 0)
+        return;
+    throw new CliCommandError(CLI_EXIT_CODES.catalog, conflictPhase === "recovery"
+        ? `unfinished Context mutation conflicts with active Long-Task Authority binding for ${conflicts.join(", ")}; first end or abandon that binding through its legitimate Long-Task lifecycle, then complete or rollback the transaction, then use a fresh Compile/rebind and any required Authority Revision; Compile, Revision, and activation cannot bypass the unfinished journal`
+        : `active Long-Task Authority binds ${conflicts.join(", ")}; end or abandon that binding through its legitimate Long-Task lifecycle before starting Context mutation; after the mutation, use a fresh Compile/rebind and Authority Revision only if the lifecycle requires it`);
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,4 @@
+import type { ContextMutationStatus } from "./mutation-types.js";
+export declare function contextMutationStatus(repository: string): Promise<ContextMutationStatus>;
+export declare function completeContextMutation(repository: string): Promise<ContextMutationStatus>;
+export declare function rollbackContextMutation(repository: string): Promise<ContextMutationStatus>;

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

@@ -0,0 +1,189 @@
+import { applyMutationChangeBackward, applyMutationChangeForward, assertMutationChangesContentState, captureMutationFileState, mutationChangeDisposition, prepareMutationTemporaryForRecovery, } from "./mutation-cas.js";
+import { cleanupContextMutationTemporaries, finishContextMutation, } from "./mutation-commit.js";
+import { mutationDirectoryStatus, prepareMutationDirectories, rollbackMutationDirectories, } from "./mutation-directories.js";
+import { assertSameContextMutationJournalSnapshot, readContextMutationJournal, updateContextMutationJournal, } from "./mutation-journal.js";
+import { contextMutationAffectedPaths, withContextMutationAuthorityInterlock, } from "./mutation-long-task-guard.js";
+import { validateLiveContextMutation, validateRolledBackContextMutation, } from "./mutation-live-validation.js";
+import { canonicalJson } from "../strict-codec.js";
+import { mutationPhysicalPath } from "./mutation-file-state.js";
+export async function contextMutationStatus(repository) {
+    const journal = await readContextMutationJournal(repository);
+    if (!journal)
+        return {
+            schema_version: 1,
+            journal_present: false,
+            directories: [],
+            files: [],
+            recovery_commands: [],
+        };
+    const directories = [];
+    for (const entry of journal.directories)
+        directories.push(await mutationDirectoryStatus(repository, entry));
+    const files = [];
+    for (const change of ordered(journal.files)) {
+        const state = await mutationChangeDisposition(repository, change);
+        const current = await currentDigest(repository, change);
+        files.push({ path: change.path, state, current_sha256: current });
+    }
+    return {
+        schema_version: 1,
+        journal_present: true,
+        transaction_id: journal.transaction_id,
+        operation: journal.operation,
+        state: journal.state,
+        directories,
+        files,
+        recovery_commands: [
+            "ty-context context transaction rollback",
+            "ty-context context transaction complete",
+        ],
+    };
+}
+export async function completeContextMutation(repository) {
+    const initial = await requiredJournal(repository);
+    return withContextMutationAuthorityInterlock(repository, contextMutationAffectedPaths(initial), async () => completeContextMutationLocked(repository, initial), "recovery");
+}
+async function completeContextMutationLocked(repository, initial) {
+    let journal = await requiredMatchingJournal(repository, initial);
+    await assertRecoveryLiveVector(repository, journal);
+    const previousState = journal.state;
+    journal = await updateContextMutationJournal(repository, journal, { ...journal, state: "committing" }, [previousState]);
+    await prepareMutationDirectories(repository, journal.directories);
+    const forward = ordered(journal.files);
+    for (const planned of forward) {
+        let change = journal.files.find((entry) => entry.path === planned.path);
+        if ((await mutationChangeDisposition(repository, change)) !== "after") {
+            const temporary = await prepareMutationTemporaryForRecovery(repository, change, "after");
+            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);
+        let successor = replaceJournalFile(journal, change.path, {
+            published_after: published,
+        });
+        successor = markApplied(successor, change);
+        journal = await updateContextMutationJournal(repository, journal, successor, ["committing"]);
+    }
+    journal = await updateContextMutationJournal(repository, journal, { ...journal, state: "validating" }, ["committing"]);
+    await assertMutationChangesContentState(repository, journal.files, "after");
+    await validateLiveContextMutation(repository, journal);
+    await assertMutationChangesContentState(repository, journal.files, "after");
+    await finishContextMutation(repository, journal);
+    return contextMutationStatus(repository);
+}
+export async function rollbackContextMutation(repository) {
+    const initial = await requiredJournal(repository);
+    return withContextMutationAuthorityInterlock(repository, contextMutationAffectedPaths(initial), async () => rollbackContextMutationLocked(repository, initial), "recovery");
+}
+async function rollbackContextMutationLocked(repository, initial) {
+    let journal = await requiredMatchingJournal(repository, initial);
+    await assertRecoveryLiveVector(repository, journal);
+    const previousState = journal.state;
+    journal = await updateContextMutationJournal(repository, journal, { ...journal, state: "committing" }, [previousState]);
+    const backward = ordered(journal.files).reverse();
+    for (const planned of backward) {
+        let change = journal.files.find((entry) => entry.path === planned.path);
+        if ((await mutationChangeDisposition(repository, change)) !== "before") {
+            const temporary = await prepareMutationTemporaryForRecovery(repository, change, "before");
+            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 applyMutationChangeBackward(repository, change);
+        let successor = replaceJournalFile(journal, change.path, {
+            published_before: published,
+        });
+        successor = markRolledBack(successor, change);
+        journal = await updateContextMutationJournal(repository, journal, successor, ["committing"]);
+    }
+    await assertMutationChangesContentState(repository, journal.files, "before");
+    await validateRolledBackContextMutation(repository, journal);
+    await cleanupContextMutationTemporaries(repository, journal);
+    await rollbackMutationDirectories(repository, journal.directories);
+    await finishContextMutation(repository, journal);
+    return contextMutationStatus(repository);
+}
+async function requiredMatchingJournal(repository, expected) {
+    const current = await requiredJournal(repository);
+    if (current.transaction_id !== expected.transaction_id ||
+        canonicalJson(current) !== canonicalJson(expected))
+        invalid("journal_transaction_changed");
+    assertSameContextMutationJournalSnapshot(expected, current);
+    return current;
+}
+async function requiredJournal(repository) {
+    const journal = await readContextMutationJournal(repository);
+    if (!journal)
+        invalid("journal_missing");
+    return journal;
+}
+async function assertRecoveryLiveVector(repository, journal) {
+    const conflicts = [];
+    const dispositions = [];
+    for (const change of ordered(journal.files)) {
+        const disposition = await mutationChangeDisposition(repository, change);
+        if (disposition === "conflict")
+            conflicts.push(change.path);
+        else
+            dispositions.push(disposition);
+    }
+    if (conflicts.length)
+        invalid(`recovery_conflict:${conflicts.sort().join(",")}`);
+    let observedPrefix = 0;
+    let beforeSeen = false;
+    for (const disposition of dispositions) {
+        if (disposition === "before")
+            beforeSeen = true;
+        else if (beforeSeen)
+            invalid("recovery_live_vector_not_applied_prefix");
+        else
+            observedPrefix += 1;
+    }
+    const recordedPrefix = journal.applied_paths.length;
+    const allowed = journal.state === "validating"
+        ? observedPrefix === journal.files.length
+        : journal.state === "planning" || journal.state === "prepared"
+            ? observedPrefix === 0
+            : Math.abs(observedPrefix - recordedPrefix) <= 1;
+    if (!allowed)
+        invalid(`recovery_live_vector_applied_prefix_mismatch:${journal.state}:${recordedPrefix}:${observedPrefix}`);
+}
+async function currentDigest(repository, change) {
+    return (await captureMutationFileState(repository, mutationPhysicalPath(change), {
+        allow_hardlinks: true,
+    })).sha256;
+}
+function ordered(values) {
+    return [...values].sort((left, right) => left.commit_order - right.commit_order);
+}
+function replaceJournalFile(journal, file, replacement) {
+    return {
+        ...journal,
+        files: journal.files.map((entry) => entry.path === file ? { ...entry, ...replacement } : entry),
+    };
+}
+function markApplied(journal, change) {
+    if (journal.applied_paths.includes(change.path))
+        return journal;
+    if (journal.applied_paths.length !== change.commit_order)
+        invalid(`journal_applied_paths_not_prefix:${change.path}`);
+    return {
+        ...journal,
+        applied_paths: [...journal.applied_paths, change.path],
+    };
+}
+function markRolledBack(journal, change) {
+    if (!journal.applied_paths.includes(change.path))
+        return journal;
+    if (journal.applied_paths.at(-1) !== change.path)
+        invalid(`journal_applied_paths_not_prefix:${change.path}`);
+    return { ...journal, applied_paths: journal.applied_paths.slice(0, -1) };
+}
+function invalid(reason) {
+    throw new Error(`context_mutation_invalid:${reason}`);
+}

package/dist/lib/context-mutation/mutation-staged-fs.d.ts

@@ -0,0 +1,5 @@
+import type { ContextCatalog } from "../context-catalog/catalog-types.js";
+import type { ContextFootprintState } from "./mutation-types.js";
+export declare function stagedFileOverrides(entries: Iterable<readonly [string, Uint8Array | null]>): ReadonlyMap<string, Uint8Array | null>;
+export declare function contextCatalogIdentity(catalog: ContextCatalog): string;
+export declare function contextFootprintState(catalog: ContextCatalog): ContextFootprintState;

package/dist/lib/context-mutation/mutation-staged-fs.js

@@ -0,0 +1,56 @@
+import { canonicalValueJson, sha256Hex } from "../strict-codec.js";
+export function stagedFileOverrides(entries) {
+    const result = new Map();
+    for (const [file, bytes] of entries) {
+        if (result.has(file))
+            throw new Error(`context_mutation_overlay_duplicate:${file}`);
+        result.set(file, bytes === null ? null : Buffer.from(bytes));
+    }
+    return result;
+}
+export function contextCatalogIdentity(catalog) {
+    return sha256Hex(canonicalValueJson({
+        manifest_path: catalog.manifest_path,
+        manifest_sha256: catalog.manifest_content === undefined
+            ? null
+            : sha256Hex(catalog.manifest_content),
+        areas: catalog.areas.map((entry) => ({
+            id: entry.id,
+            root: entry.root,
+            context: entry.context,
+            kind: entry.kind,
+            default: entry.default,
+        })),
+        contexts: (catalog.manifest?.contexts ?? []).map((entry) => ({
+            path: entry.path,
+            role: entry.role,
+            read_policy: entry.read_policy ?? null,
+            read_when: entry.read_when ?? null,
+            triggers: [...entry.triggers],
+            default_children: [...entry.default_children],
+        })),
+        files: catalog.context_files.map((entry) => ({
+            path: entry.path,
+            bytes: entry.bytes,
+        })),
+        default_paths: [...catalog.default_footprint.keys()],
+        errors: catalog.diagnostics
+            .filter((entry) => entry.severity === "error")
+            .map((entry) => ({
+            code: entry.code,
+            path: entry.path ?? null,
+            line: entry.line ?? null,
+        })),
+    }));
+}
+export function contextFootprintState(catalog) {
+    const sizes = new Map(catalog.context_files.map((entry) => [entry.path, entry.bytes]));
+    const paths = [...catalog.default_footprint.keys()];
+    let bytes = 0;
+    for (const file of paths)
+        bytes +=
+            file === catalog.manifest_path
+                ? Buffer.byteLength(catalog.manifest_content ?? "", "utf8")
+                : (sizes.get(file) ?? 0);
+    return { paths, path_count: paths.length, bytes };
+}

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

@@ -0,0 +1,103 @@
+import type { ContextRole } from "../context-catalog/catalog-portable-contract.js";
+export type ContextMutationOperation = "register" | "move";
+export type ContextMutationJournalState = "planning" | "prepared" | "committing" | "validating";
+export interface MutationFileIdentity {
+    dev: string;
+    ino: string;
+    nlink: string;
+    size: string;
+    mtime_ns: string;
+    ctime_ns: string;
+}
+export interface MutationFileState {
+    exists: boolean;
+    sha256: string | null;
+    bytes_base64: string | null;
+    mode: number | null;
+    identity: MutationFileIdentity | null;
+}
+export interface MutationRecordedFileState {
+    exists: boolean;
+    sha256: string | null;
+    mode: number | null;
+    identity: MutationFileIdentity | null;
+}
+export interface MutationTemporaryState {
+    side: "before" | "after";
+    state: MutationRecordedFileState;
+}
+export interface MutationFileChange {
+    path: string;
+    physical_path?: string;
+    before: MutationFileState;
+    after: MutationFileState;
+    commit_order: number;
+    temporary_path: string | null;
+    temporary_state: MutationTemporaryState | null;
+    published_before: MutationRecordedFileState | null;
+    published_after: MutationRecordedFileState | null;
+}
+export interface MutationDirectoryChange {
+    path: string;
+    before_exists: false;
+}
+export interface RegisterMutationData {
+    kind: "register";
+    context_path: string;
+    role: ContextRole;
+    read_policy: string;
+    expected_default_paths: string[];
+    expected_default_bytes: number;
+}
+export interface MoveMutationData {
+    kind: "move";
+    from_path: string;
+    to_path: string;
+    owner_source: "area" | "context";
+    role: ContextRole;
+    read_policy: string | null;
+    expected_reference_issues: string[];
+    expected_default_paths: string[];
+    expected_default_bytes: number;
+}
+export type ContextMutationOperationData = RegisterMutationData | MoveMutationData;
+export interface ContextMutationPlan {
+    transaction_id: string;
+    operation: ContextMutationOperation;
+    catalog_before_identity: string;
+    catalog_after_identity: string;
+    directories: MutationDirectoryChange[];
+    files: MutationFileChange[];
+    operation_data: ContextMutationOperationData;
+}
+export interface ContextMutationJournal extends ContextMutationPlan {
+    schema_version: "context-mutation-journal-v2" | "context-mutation-journal-v3";
+    journal_sequence: number;
+    previous_journal_sha256: string | null;
+    state: ContextMutationJournalState;
+    applied_paths: string[];
+}
+export interface MutationFileStatus {
+    path: string;
+    state: "before" | "after" | "conflict";
+    current_sha256: string | null;
+}
+export interface MutationDirectoryStatus {
+    path: string;
+    state: "absent" | "directory" | "conflict";
+}
+export interface ContextMutationStatus {
+    schema_version: 1;
+    journal_present: boolean;
+    transaction_id?: string;
+    operation?: ContextMutationOperation;
+    state?: ContextMutationJournalState;
+    directories: MutationDirectoryStatus[];
+    files: MutationFileStatus[];
+    recovery_commands: string[];
+}
+export interface ContextFootprintState {
+    paths: string[];
+    path_count: number;
+    bytes: number;
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/lib/context-register/context-register-input.d.ts

@@ -0,0 +1,11 @@
+import { type ContextRole } from "../context-catalog/catalog-portable-contract.js";
+import type { ContextRegisterInput } from "./context-register-types.js";
+export interface NormalizedRegisterInput {
+    path: string;
+    role: ContextRole;
+    read_policy: "default" | "on-demand";
+    read_when?: string;
+    triggers: string[];
+    default_children: string[];
+}
+export declare function normalizeContextRegisterInput(input: ContextRegisterInput): NormalizedRegisterInput;

package/dist/lib/context-register/context-register-input.js

@@ -0,0 +1,43 @@
+import { CLI_EXIT_CODES, CliCommandError } from "../cli-exit.js";
+import { normalizeContextRole, } from "../context-catalog/catalog-portable-contract.js";
+import { normalizeContextPath } from "../context-catalog/catalog-paths.js";
+import { normalizeContextFilePath } from "../context-create/context-create-path.js";
+const CURRENT_POLICIES = new Set(["default", "on-demand"]);
+export function normalizeContextRegisterInput(input) {
+    const contextPath = normalizeContextFilePath(input.context_path, "context register");
+    const role = normalizeContextRole(input.role);
+    if (!role)
+        argumentFailure(`context register has unsupported role: ${input.role}`);
+    const readPolicy = input.read_policy ?? "on-demand";
+    if (!CURRENT_POLICIES.has(readPolicy))
+        argumentFailure("context register --read-policy must be default or on-demand");
+    return {
+        path: contextPath,
+        role,
+        read_policy: readPolicy,
+        read_when: optionalBoundedText(input.read_when, "read-when", 1024),
+        triggers: boundedUniqueValues(input.triggers ?? [], "trigger", 64, 128),
+        default_children: boundedUniqueValues((input.default_children ?? []).map(normalizeContextPath), "default-child", 64, 512),
+    };
+}
+function optionalBoundedText(value, label, maximum) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.normalize("NFC").trim();
+    if (!normalized || [...normalized].length > maximum)
+        argumentFailure(`context register --${label} must contain 1-${maximum} code points`);
+    return normalized;
+}
+function boundedUniqueValues(values, label, maximumCount, maximumLength) {
+    if (values.length > maximumCount)
+        argumentFailure(`context register accepts at most ${maximumCount} --${label} values`);
+    const normalized = values.map((value) => value.normalize("NFC").trim());
+    if (normalized.some((value) => !value || [...value].length > maximumLength))
+        argumentFailure(`context register --${label} values must contain 1-${maximumLength} code points`);
+    if (new Set(normalized).size !== normalized.length)
+        argumentFailure(`context register has duplicate --${label} values`);
+    return normalized;
+}
+function argumentFailure(messageText) {
+    throw new CliCommandError(CLI_EXIT_CODES.arguments, messageText);
+}

package/dist/lib/context-register/context-register-render.d.ts

@@ -0,0 +1,2 @@
+import type { ContextRegisterResult } from "./context-register-types.js";
+export declare function renderContextRegisterText(result: ContextRegisterResult): string;