project-tiny-context-harness 0.8.17 → 0.12.0

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 { withContextMutationInterlock } from "./mutation-interlock.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 withContextMutationInterlock(repository, async () => completeContextMutationLocked(repository, initial));
+}
+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 withContextMutationInterlock(repository, async () => rollbackContextMutationLocked(repository, initial));
+}
+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-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;

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

@@ -0,0 +1,21 @@
+export function renderContextRegisterText(result) {
+    const lines = [
+        `Context register ${result.applied ? "committed" : "dry-run"}`,
+        `Path: ${result.path}`,
+        `Role: ${result.role}`,
+        `Read policy: ${result.read_policy}`,
+        `Manifest: ${result.manifest.before_sha256} -> ${result.manifest.after_sha256} (${signed(result.manifest.bytes_delta)} bytes)`,
+        `Default footprint: ${result.default_footprint.before.path_count}/${result.default_footprint.before.bytes} -> ${result.default_footprint.after.path_count}/${result.default_footprint.after.bytes}`,
+        `Transaction: ${result.transaction.id} (${result.transaction.state})`,
+        "",
+        result.manifest.diff.trimEnd(),
+    ];
+    for (const diagnostic of result.diagnostics)
+        lines.push(`warning: ${diagnostic}`);
+    if (!result.applied)
+        lines.push("", "No files changed. Re-run with --apply to commit this exact plan after a fresh CAS check.");
+    return `${lines.join("\n")}\n`;
+}
+function signed(value) {
+    return value >= 0 ? `+${value}` : String(value);
+}

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

@@ -0,0 +1,6 @@
+import type { CatalogFile, ContextCatalog } from "../context-catalog/catalog-types.js";
+import type { NormalizedRegisterInput } from "./context-register-input.js";
+export declare function assertRegistrationTarget(catalog: ContextCatalog, contextPath: string): CatalogFile;
+export declare function assertStagedRegistration(catalog: ContextCatalog, input: NormalizedRegisterInput): void;
+export declare function readContextContent(repository: string, file: CatalogFile): Promise<string>;
+export declare function renderAppendDiff(file: string, block: string): string;

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

@@ -0,0 +1,46 @@
+import { readFile } from "node:fs/promises";
+import { portableContextPathCaseKey } from "../context-catalog/catalog-paths.js";
+import { decodeMutationUtf8, mutationCatalogFailure, mutationIoFailure, mutationMessage, } from "../context-mutation/mutation-command-support.js";
+import { assertProtectedRepositoryFile } from "../repository-path-safety.js";
+export function assertRegistrationTarget(catalog, contextPath) {
+    const folded = portableContextPathCaseKey(contextPath);
+    const registered = catalog.registered_contexts.find((entry) => portableContextPathCaseKey(entry.path) === folded);
+    if (registered)
+        mutationCatalogFailure(`Context is already registered as ${registered.path}`);
+    const file = catalog.unregistered_context_files.find((entry) => portableContextPathCaseKey(entry.path) === folded);
+    if (!file)
+        mutationIoFailure(`context register requires an existing unregistered file: ${contextPath}`);
+    if (file.path !== contextPath)
+        mutationIoFailure(`context register path case does not match existing file: ${file.path}`);
+    return file;
+}
+export function assertStagedRegistration(catalog, input) {
+    const matches = catalog.registered_contexts.filter((entry) => entry.source === "context" && entry.path === input.path);
+    if (matches.length !== 1)
+        mutationCatalogFailure("staged registration is not unique");
+    if (matches[0].role !== input.role ||
+        matches[0].read_policy !== input.read_policy)
+        mutationCatalogFailure("staged registration metadata does not match the request");
+}
+export async function readContextContent(repository, file) {
+    try {
+        const absolute = await assertProtectedRepositoryFile(repository, file.absolute_path, "context_register_source");
+        return decodeMutationUtf8(await readFile(absolute), file.path);
+    }
+    catch (error) {
+        mutationIoFailure(`unable to read Context registration source: ${mutationMessage(error)}`, error);
+    }
+}
+export function renderAppendDiff(file, block) {
+    return [
+        `--- ${file}`,
+        `+++ ${file}`,
+        "@@ append context @@",
+        ...block
+            .replace(/\r\n/gu, "\n")
+            .trimEnd()
+            .split("\n")
+            .map((line) => `+${line}`),
+        "",
+    ].join("\n");
+}

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

@@ -0,0 +1,46 @@
+import type { ContextRole } from "../context-catalog/catalog-portable-contract.js";
+import type { ContextFootprintState } from "../context-mutation/mutation-types.js";
+export interface ContextRegisterInput {
+    project_root: string;
+    context_path: string;
+    role: string;
+    read_policy?: string;
+    read_when?: string;
+    triggers?: string[];
+    default_children?: string[];
+    apply?: boolean;
+}
+export interface ContextRegisterResult {
+    schema_version: 1;
+    operation: "register";
+    applied: boolean;
+    path: string;
+    role: ContextRole;
+    read_policy: "default" | "on-demand";
+    manifest: {
+        path: "project_context/context.toml";
+        before_sha256: string;
+        after_sha256: string;
+        before_bytes: number;
+        after_bytes: number;
+        bytes_delta: number;
+        diff: string;
+    };
+    default_footprint: {
+        changed: boolean;
+        before: ContextFootprintState;
+        after: ContextFootprintState;
+        added: string[];
+        removed: string[];
+    };
+    catalog: {
+        before_identity: string;
+        after_identity: string;
+    };
+    diagnostics: string[];
+    transaction: {
+        id: string;
+        state: "dry-run" | "committed";
+        journal_present: false;
+    };
+}

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

@@ -0,0 +1,8 @@
+import type { ContextMutationPlan } from "../context-mutation/mutation-types.js";
+import type { ContextRegisterInput, ContextRegisterResult } from "./context-register-types.js";
+export declare function registerContext(input: ContextRegisterInput): Promise<ContextRegisterResult>;
+export interface PlannedContextRegistration {
+    plan: ContextMutationPlan;
+    result: ContextRegisterResult;
+}
+export declare function planContextRegistration(input: ContextRegisterInput): Promise<PlannedContextRegistration>;