project-tiny-context-harness 0.11.0 → 0.12.0

package/dist/lib/retirement-references.js

@@ -0,0 +1,102 @@
+import { captureMutationFileState } from "./context-mutation/mutation-file-state.js";
+import { extractContextMarkdown } from "./context-markdown/context-markdown-extract.js";
+import { resolveContextControllingSourceDeclaration } from "./context-controlling-source.js";
+// A one-time, bounded migration review. This is neither a historical-resource
+// compiler nor a general link validator. Only declared controlling inputs and
+// executable package scripts are blocking dependencies here.
+export async function inspectRetirementReferences(repository, catalog, changes) {
+    const blockers = [], review = [];
+    const files = new Set(catalog.context_files.map((file) => file.path));
+    files.add("DESIGN.md");
+    files.add("AGENTS.override.md");
+    const queue = [...files].map((file) => ({
+        file,
+        required: false,
+        via: file,
+    }));
+    const visited = new Set();
+    while (queue.length) {
+        const { file, required, via } = queue.shift();
+        const key = `${required}:${file}`;
+        if (visited.has(key))
+            continue;
+        visited.add(key);
+        let state;
+        try {
+            state = await captureMutationFileState(repository, file);
+        }
+        catch (error) {
+            (required ? blockers : review).push(`${via} -> ${file}: ${String(error)}`);
+            continue;
+        }
+        if (!state.exists) {
+            if (required)
+                blockers.push(`${via} -> ${file}: required local input missing`);
+            continue;
+        }
+        if (Number(state.identity?.size ?? 0) > 2_000_000) {
+            (required ? blockers : review).push(`${via} -> ${file}: exceeds the 2 MB migration inspection scope; extract necessary requirements and source locations before retiring its decoder`);
+            continue;
+        }
+        const content = Buffer.from(state.bytes_base64, "base64").toString("utf8");
+        const retiredRepresentation = /(?:semantic-fact-compact-carrier-v1|long-task-compact-carrier-v1|design-resource-handoff-v2|symbolic_rules_v2|symbolic-denotation-canonical-dag-v1|design-resource-symbolic-source-ir-v1)/.exec(content);
+        if (required && retiredRepresentation)
+            blockers.push(`${via} -> ${file}: ${retiredRepresentation[0]} requires retired interpretation; extract the required values, adopted decisions and locators into a directly readable source with provenance, then update the controlling reference`);
+        if (!file.endsWith(".md"))
+            continue;
+        const parsed = extractContextMarkdown(content, file);
+        for (const declaration of parsed.controlling_sources) {
+            const resolved = await resolveContextControllingSourceDeclaration(repository, declaration);
+            const locator = `${file}:${declaration.line} (${declaration.declared_path})`;
+            if (resolved.status !== "valid" || !resolved.target_path)
+                blockers.push(`${locator}: ${resolved.detail ?? resolved.status}`);
+            else
+                queue.push({
+                    file: resolved.target_path,
+                    required: true,
+                    via: locator,
+                });
+        }
+        for (const reference of parsed.references)
+            if (!/^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i.test(reference.destination))
+                review.push(`${file}:${reference.line}: follow local resource ${reference.destination} if still selected; ordinary links and historical examples are not migration blockers or compiler-resolved inputs`);
+        content.split(/\r?\n/).forEach((line, index) => {
+            if (/Final Gate|\$long-task-workflow|\bty-context\s+(?:long-task|design-resource|design-authority)\b/.test(line))
+                review.push(`${file}:${index + 1}: review old workflow wording; retain historical facts and independent user constraints, revise any still-effective requirement explicitly`);
+        });
+    }
+    const packages = new Set([
+        "package.json",
+        ...catalog.areas.map((area) => `${area.root.replace(/\/$/, "")}/package.json`),
+    ]);
+    for (const file of packages) {
+        try {
+            const state = await captureMutationFileState(repository, file);
+            if (!state.exists)
+                continue;
+            const raw = JSON.parse(Buffer.from(state.bytes_base64, "base64").toString("utf8"));
+            for (const [name, command] of Object.entries(raw.scripts ?? {}))
+                if (typeof command === "string" && retiredCommand(command))
+                    blockers.push(`${file} scripts.${name}: invokes a retired command; replace or move the build dependency and verify its derived outputs before upgrading`);
+        }
+        catch (error) {
+            blockers.push(`${file}: build configuration could not be inspected: ${String(error)}`);
+        }
+    }
+    const makeChange = changes.find((file) => file.path === "Makefile");
+    const makeState = await captureMutationFileState(repository, "Makefile");
+    const make = makeChange
+        ? (makeChange.after ?? "")
+        : makeState.exists
+            ? Buffer.from(makeState.bytes_base64, "base64").toString("utf8")
+            : "";
+    make.split(/\r?\n/).forEach((line, index) => {
+        if (/^\t/.test(line) && retiredCommand(line))
+            blockers.push(`Makefile:${index + 1}: retained recipe invokes a retired command; replace its build dependency before upgrade`);
+    });
+    review.push("Inspected declared controlling-source inputs, Context/DESIGN local links, root and manifest-Area package scripts, and retained Makefile recipes. Direct Markdown/JSON/YAML fields stay readable. Structured IDs, compact expansion, symbolic evaluation, arbitrary CI/shell indirection and unreferenced history are not interpreted; review current task/selected resources and other build entrypoints separately. Project-information migration is not automatically certified.");
+    return { blockers, review: [...new Set(review)] };
+}
+function retiredCommand(value) {
+    return /(?:\bty-context|(?:^|[\s"'])[^\s"']*dist[\\/]cli\.js)["']?\s+(?:long-task|design-resource|design-authority|validate-harness|validate-code-modularity|check-modularity|route|enable|disable|delivery-set|composite-long-task|composite-campaign)\b/.test(value);
+}

package/dist/lib/retirement-runner.d.ts

@@ -0,0 +1,22 @@
+import type { MutationFileChange } from "./context-mutation/mutation-types.js";
+import { type RetirementPlan } from "./retirement-plan.js";
+export declare const RETIREMENT_PENDING = "tmp/ty-context/upgrade-schema-5.json";
+interface RetirementJournal {
+    format: "tiny-context-schema5-upgrade-v1";
+    id: string;
+    repository: string;
+    files: MutationFileChange[];
+    defaults: string[];
+    review: string[];
+    binding: RetirementPlan["binding"];
+}
+export interface RetirementRunOptions {
+    sessions_stopped?: boolean;
+    checkpoint?: (name: string) => Promise<void>;
+}
+export declare function runSchema5Retirement(repository: string, options?: RetirementRunOptions): Promise<{
+    lines: string[];
+    blocked: boolean;
+}>;
+export declare function readRetirementJournal(repository: string): Promise<RetirementJournal | null>;
+export {};

package/dist/lib/retirement-runner.js

@@ -0,0 +1,217 @@
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { captureMutationFileState, mutationFileStateFromBytes, absentMutationFileState, mutationRecordedFileState, } from "./context-mutation/mutation-file-state.js";
+import { mutationTemporaryPath, stageMutationTemporary, prepareMutationTemporaryForRecovery, mutationChangeDisposition, applyMutationChangeForward, cleanupMutationTemporary, } from "./context-mutation/mutation-cas.js";
+import { validateJournalFileState, validateJournalRecordedFileState, } from "./context-mutation/mutation-journal-validation-support.js";
+import { ensureSafeRepositoryDirectory, resolveInsideRepository, } from "./repository-path-safety.js";
+import { withMaintenanceLock } from "./maintenance-lock.js";
+import { writeMaintenanceText, removeMaintenanceFile, } from "./maintenance-write.js";
+import { planSchema5Retirement, } from "./retirement-plan.js";
+import { assertLegacyContextTransactionSettled } from "./retirement-preflight.js";
+import { retireOwnBinding } from "./retirement-binding.js";
+import { runValidator } from "./validators.js";
+import { loadContextCatalog } from "./context-catalog/catalog-load.js";
+import { canonicalJson } from "./strict-codec.js";
+export const RETIREMENT_PENDING = "tmp/ty-context/upgrade-schema-5.json";
+export async function runSchema5Retirement(repository, options = {}) {
+    await assertLegacyContextTransactionSettled(repository);
+    return withMaintenanceLock(repository, "upgrade", async () => {
+        await assertLegacyContextTransactionSettled(repository);
+        let journal = await readRetirementJournal(repository);
+        if (!journal) {
+            const plan = await planSchema5Retirement(repository);
+            if (plan.blockers.length)
+                return { lines: plan.blockers, blocked: true };
+            if (!plan.files.length)
+                return { lines: ["No schema retirement pending."], blocked: false };
+            if (!options.sessions_stopped)
+                return {
+                    lines: [
+                        "Before retirement, stop the relevant old host sessions, then retry upgrade --sessions-stopped. Locks alone cannot establish that sessions stopped.",
+                    ],
+                    blocked: true,
+                };
+            journal = createJournal(repository, plan);
+            await ensureSafeRepositoryDirectory(repository, "tmp/ty-context/upgrade-backups", "upgrade_backup");
+            await writeMaintenanceText(repository, `tmp/ty-context/upgrade-backups/${journal.id}.json`, canonicalJson(journal));
+            await writeMaintenanceText(repository, RETIREMENT_PENDING, canonicalJson(journal));
+            await options.checkpoint?.("prepared");
+        }
+        else if (!options.sessions_stopped)
+            return {
+                lines: [
+                    "An unfinished upgrade exists. Stop relevant old sessions and resume with upgrade --sessions-stopped; original file bytes remain in the upgrade backup.",
+                ],
+                blocked: true,
+            };
+        const save = async () => writeMaintenanceText(repository, RETIREMENT_PENDING, canonicalJson(journal));
+        for (const change of journal.files) {
+            await reconcileUnrecordedTemporary(repository, change);
+            await save();
+            let disposition = await mutationChangeDisposition(repository, change);
+            if (disposition === "conflict")
+                throw new Error(`upgrade_conflict:${change.path}; preserve the changed file and consult backup ${journal.id}`);
+            if (disposition !== "after") {
+                await ensureSafeRepositoryDirectory(repository, path.posix.dirname(change.path), "upgrade_file_parent");
+                if (!change.temporary_state) {
+                    change.temporary_state = change.after.exists
+                        ? await stageMutationTemporary(repository, change)
+                        : await prepareMutationTemporaryForRecovery(repository, change, "after");
+                    await save();
+                }
+                await options.checkpoint?.(`staged:${change.path}`);
+                change.published_after = await applyMutationChangeForward(repository, change);
+                await options.checkpoint?.(`published:${change.path}`);
+                await save();
+            }
+            else if (!change.published_after) {
+                change.published_after = await applyMutationChangeForward(repository, change);
+                await save();
+            }
+        }
+        const validation = await runValidator(repository, "validate-context");
+        if (validation.errors.length)
+            throw new Error(`upgrade_validation_failed:${validation.errors.join("; ")}`);
+        const actual = [
+            ...(await loadContextCatalog(repository)).default_footprint.keys(),
+        ].sort();
+        if (JSON.stringify(actual) !== JSON.stringify(journal.defaults))
+            throw new Error("upgrade_default_set_changed; restore or reconcile using the retained backup");
+        for (const change of journal.files) {
+            if ((await mutationChangeDisposition(repository, change)) !== "after")
+                throw new Error(`upgrade_final_file_changed:${change.path}; preserve pending recovery and the original backup`);
+        }
+        await retireOwnBinding(repository, journal.binding);
+        await options.checkpoint?.("binding_retired");
+        for (const change of journal.files)
+            await cleanupMutationTemporary(repository, change);
+        const pending = await captureMutationFileState(repository, RETIREMENT_PENDING);
+        await removeMaintenanceFile(repository, RETIREMENT_PENDING, pending);
+        return {
+            lines: [
+                `Schema-5 software migration complete; backup: tmp/ty-context/upgrade-backups/${journal.id}.json`,
+                "Default body selection preserved exactly. Start a new host session; loaded old instructions do not disappear with files.",
+                ...journal.review,
+            ],
+            blocked: false,
+        };
+    });
+}
+export async function readRetirementJournal(repository) {
+    const state = await captureMutationFileState(repository, RETIREMENT_PENDING);
+    if (!state.exists)
+        return null;
+    const journal = JSON.parse(Buffer.from(state.bytes_base64, "base64").toString("utf8"));
+    if (journal.format !== "tiny-context-schema5-upgrade-v1" ||
+        journal.repository !== path.resolve(repository) ||
+        !/^[0-9a-f-]{36}$/.test(journal.id) ||
+        !Array.isArray(journal.files) ||
+        !Array.isArray(journal.defaults) ||
+        !Array.isArray(journal.review))
+        throw new Error("invalid upgrade journal; preserve it and recover from its original backup");
+    const paths = new Set();
+    for (const [index, file] of journal.files.entries()) {
+        resolveInsideRepository(repository, file.path, "upgrade_journal_path");
+        if (file.physical_path !== undefined ||
+            paths.has(file.path) ||
+            file.commit_order !== index ||
+            file.temporary_path !==
+                mutationTemporaryPath(file.path, journal.id, index))
+            throw new Error("invalid upgrade file ordering or temporary path");
+        paths.add(file.path);
+        validateJournalFileState(file.before, "upgrade.before");
+        validateJournalFileState(file.after, "upgrade.after");
+        if (file.temporary_state)
+            validateJournalRecordedFileState(file.temporary_state.state, "upgrade.temporary");
+        if (file.published_after)
+            validateJournalRecordedFileState(file.published_after, "upgrade.published");
+    }
+    const backup = await captureMutationFileState(repository, `tmp/ty-context/upgrade-backups/${journal.id}.json`);
+    if (!backup.exists)
+        throw new Error("upgrade_original_backup_missing; do not continue from an unbound journal");
+    const original = JSON.parse(Buffer.from(backup.bytes_base64, "base64").toString("utf8"));
+    if (canonicalJson(immutablePlan(journal)) !==
+        canonicalJson(immutablePlan(original)))
+        throw new Error("upgrade_journal_plan_changed; reconcile with the original backup before continuing");
+    return journal;
+}
+function immutablePlan(journal) {
+    return {
+        ...journal,
+        files: journal.files.map((file) => ({
+            ...file,
+            temporary_state: null,
+            published_before: null,
+            published_after: null,
+        })),
+    };
+}
+function createJournal(repository, plan) {
+    const id = randomUUID();
+    return {
+        format: "tiny-context-schema5-upgrade-v1",
+        id,
+        repository: path.resolve(repository),
+        defaults: plan.defaults,
+        review: plan.review,
+        binding: plan.binding,
+        files: plan.files
+            .filter((file) => file.after === null
+            ? file.before.exists
+            : file.before.bytes_base64 !==
+                Buffer.from(file.after).toString("base64"))
+            .map((file, index) => ({
+            path: file.path,
+            before: file.before,
+            after: file.after === null
+                ? absentMutationFileState()
+                : mutationFileStateFromBytes(Buffer.from(file.after), file.before.mode ??
+                    (process.platform === "win32"
+                        ? 0o666
+                        : 0o666 & ~process.umask())),
+            commit_order: index,
+            temporary_path: mutationTemporaryPath(file.path, id, index),
+            temporary_state: null,
+            published_before: null,
+            published_after: null,
+        })),
+    };
+}
+async function reconcileUnrecordedTemporary(repository, file) {
+    if (file.temporary_state)
+        return;
+    const temporary = await captureMutationFileState(repository, file.temporary_path, { allow_hardlinks: true });
+    if (!temporary.exists)
+        return;
+    const current = await captureMutationFileState(repository, file.path, {
+        allow_hardlinks: true,
+    });
+    if (file.after.exists &&
+        temporary.sha256 === file.after.sha256 &&
+        temporary.mode === file.after.mode &&
+        temporary.identity?.nlink === "1" &&
+        current.sha256 === file.before.sha256 &&
+        current.exists === file.before.exists) {
+        file.temporary_state = {
+            side: "after",
+            state: mutationRecordedFileState(temporary),
+        };
+        return;
+    }
+    if (!file.after.exists &&
+        current.sha256 === file.before.sha256 &&
+        temporary.sha256 === file.before.sha256 &&
+        current.identity?.ino === file.before.identity?.ino &&
+        current.identity?.dev === file.before.identity?.dev &&
+        temporary.identity?.ino === current.identity?.ino &&
+        temporary.identity?.dev === current.identity?.dev &&
+        temporary.identity?.nlink === "2" &&
+        current.identity?.nlink === "2") {
+        file.temporary_state = {
+            side: "before",
+            state: mutationRecordedFileState(temporary),
+        };
+        return;
+    }
+    throw new Error(`upgrade_temporary_conflict:${file.temporary_path}; do not delete or overwrite an unrecognized recovery file`);
+}

package/dist/lib/schema-guard.d.ts

@@ -1,3 +1,4 @@
 export declare function assertSupportedSchema(projectRoot: string, commandName: string): Promise<void>;
+export declare function rawSchemaVersion(projectRoot: string): Promise<string | undefined>;
 export declare function unsupportedSchemaMessage(schemaVersion: string, commandName: string): string | undefined;
 export declare function schemaMajor(schemaVersion: string): number | undefined;

package/dist/lib/schema-guard.js

@@ -1,17 +1,58 @@
-import { readConfig } from "./config.js";
+import { readFile, lstat } from "node:fs/promises";
+import path from "node:path";
+import { harnessConfigPath } from "./harness-root.js";
+import { parseYaml } from "./yaml.js";
+import { assertProtectedRepositoryFile } from "./repository-path-safety.js";
 import { CANONICAL_NPX_COMMAND, CURRENT_SCHEMA_VERSION } from "./constants.js";
 export async function assertSupportedSchema(projectRoot, commandName) {
-    const config = await readConfig(projectRoot);
-    const message = unsupportedSchemaMessage(config.core.schema_version, commandName);
+    if (commandName !== "upgrade") {
+        try {
+            await lstat(path.join(projectRoot, "tmp/ty-context/upgrade-schema-5.json"));
+            throw new Error("upgrade_incomplete: resume the explicit schema-5 upgrade before other writes");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    const version = await rawSchemaVersion(projectRoot);
+    if (version === undefined)
+        return;
+    const message = unsupportedSchemaMessage(version, commandName);
     if (message) {
         throw new Error(message);
     }
+    if (version !== CURRENT_SCHEMA_VERSION && commandName !== "upgrade")
+        throw new Error(`upgrade_required: schema ${version}; run explicit ty-context upgrade before ${commandName}. No files were changed by this guard.`);
+}
+export async function rawSchemaVersion(projectRoot) {
+    const relative = await harnessConfigPath(projectRoot);
+    const file = path.join(projectRoot, relative);
+    try {
+        await lstat(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    await assertProtectedRepositoryFile(projectRoot, file, "harness_config");
+    const raw = parseYaml(await readFile(file, "utf8"));
+    const version = raw?.core?.schema_version;
+    if ((typeof version !== "string" && typeof version !== "number") ||
+        !/^\d+$/.test(String(version)))
+        throw new Error(`${relative}: missing or invalid raw core.schema_version; repair explicitly before writing`);
+    if (String(version) === CURRENT_SCHEMA_VERSION &&
+        raw &&
+        ("profiles" in raw || "modularity" in raw))
+        throw new Error(`${relative}: retired_config_fields; schema 5 cannot run old profiles/modularity. Reconcile unsupported old-CLI changes before writing.`);
+    return String(version);
 }
 export function unsupportedSchemaMessage(schemaVersion, commandName) {
     const projectMajor = schemaMajor(schemaVersion);
     const supportedMajor = schemaMajor(CURRENT_SCHEMA_VERSION);
-    if (projectMajor === undefined ||
-        supportedMajor === undefined ||
+    if (projectMajor !== undefined &&
+        supportedMajor !== undefined &&
         projectMajor <= supportedMajor) {
         return undefined;
     }
@@ -22,7 +63,7 @@ export function unsupportedSchemaMessage(schemaVersion, commandName) {
     ].join(". ");
 }
 export function schemaMajor(schemaVersion) {
-    const match = /^(\d+)/.exec(String(schemaVersion).trim());
+    const match = /^(\d+)$/.exec(String(schemaVersion).trim());
     if (!match) {
         return undefined;
     }

package/dist/lib/source-files.d.ts

@@ -1,6 +1,4 @@
 export declare const SAFE_EXAMPLE_FILE_NAMES: Set<string>;
-export type ModularityAnalysisCapability = "js-ts-heuristic" | "python-heuristic" | "line-only";
 export declare function shouldIncludeCodeFile(relative: string): boolean;
-export declare function modularityAnalysisCapability(relative: string): ModularityAnalysisCapability | undefined;
 export declare function shouldExcludeRelativePath(relative: string): boolean;
 export declare function toPosix(value: string): string;

package/dist/lib/source-files.js

@@ -90,14 +90,6 @@ const CONFIG_JSON_NAMES = new Set([
     "tsconfig.json",
     "vite.config.json",
 ]);
-const JS_TS_HEURISTIC_EXTENSIONS = new Set([
-    ".cjs",
-    ".js",
-    ".jsx",
-    ".mjs",
-    ".ts",
-    ".tsx",
-]);
 export function shouldIncludeCodeFile(relative) {
     if (shouldExcludeRelativePath(relative)) {
         return false;
@@ -116,19 +108,6 @@ export function shouldIncludeCodeFile(relative) {
     }
     return CODE_FILE_EXTENSIONS.some((extension) => lower.endsWith(extension));
 }
-export function modularityAnalysisCapability(relative) {
-    if (!shouldIncludeCodeFile(relative)) {
-        return undefined;
-    }
-    const extension = path.posix.extname(toPosix(relative).toLowerCase());
-    if (JS_TS_HEURISTIC_EXTENSIONS.has(extension)) {
-        return "js-ts-heuristic";
-    }
-    if (extension === ".py") {
-        return "python-heuristic";
-    }
-    return "line-only";
-}
 export function shouldExcludeRelativePath(relative) {
     const normalized = toPosix(relative);
     const segments = normalized.split("/");

package/dist/lib/source-pack-export.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { assertSupportedSchema } from "./schema-guard.js";
 import { artifactReport, buildManifest, pruneTimestampedExports, readPackageVersion, writeArtifactSet, } from "./source-pack-manifest.js";
 import { mergePatterns, parseContextAreas, readSourcePackProfile, validatePatternList, } from "./source-pack-config.js";
 import { collectCodeRecords, collectContextArtifacts, countRedactionWarnings, repoRelative, } from "./source-pack-records.js";
@@ -7,6 +8,8 @@ const DEFAULT_EXPORT_DIR = "tmp/ty-context/context-exports";
 const DEFAULT_MAX_PACK_FILES = 5;
 const DEFAULT_MAX_BUNDLE_CHARACTERS = 800_000;
 export async function runSourcePackExport(projectRoot, options) {
+    if (!options.check)
+        await assertSupportedSchema(projectRoot, "export-context");
     const maxPackFiles = options.maxPackFiles ?? DEFAULT_MAX_PACK_FILES;
     validateMaxPackFiles(options.mode, maxPackFiles);
     const now = options.now ?? new Date();
@@ -90,7 +93,7 @@ export async function runSourcePackExport(projectRoot, options) {
     }
     if (!options.check) {
         await writeArtifactSet(projectRoot, outputDir, artifacts);
-        await pruneTimestampedExports(projectRoot, 0);
+        await pruneTimestampedExports(projectRoot, options.prune ?? 0);
     }
     return {
         mode: options.mode,

package/dist/lib/source-pack-manifest.js

@@ -2,7 +2,11 @@ import { execFile } from "node:child_process";
 import path from "node:path";
 import { promisify } from "node:util";
 import { promises as fs } from "node:fs";
-import { ensureDir, writeTextIfChanged } from "./fs.js";
+import { ensureSafeRepositoryDirectory, assertProtectedRepositoryDirectory, normalizeRepositoryFile, } from "./repository-path-safety.js";
+import { captureMutationFileState } from "./context-mutation/mutation-file-state.js";
+import { writeMaintenanceText, removeMaintenanceFile, } from "./maintenance-write.js";
+import { withMaintenanceLock } from "./maintenance-lock.js";
+import { assertSupportedSchema } from "./schema-guard.js";
 import { repoRelative, sha256 } from "./source-pack-records.js";
 const execFileAsync = promisify(execFile);
 export async function buildManifest(params) {
@@ -36,35 +40,97 @@ export function artifactReport(artifact) {
     };
 }
 export async function writeArtifactSet(projectRoot, outputDir, artifacts) {
-    const outputRelative = repoRelative(projectRoot, outputDir);
-    if (!outputRelative.startsWith("tmp/ty-context/context-exports/")) {
-        throw new Error("Source Pack output directory must stay under tmp/ty-context/context-exports/**");
+    const relative = repoRelative(projectRoot, outputDir);
+    if (relative !== "tmp/ty-context/context-exports/latest")
+        throw Error("Source Pack output must use its owned latest directory");
+    await withMaintenanceLock(projectRoot, "export", async () => {
+        await assertSupportedSchema(projectRoot, "export-context");
+        await ensureSafeRepositoryDirectory(projectRoot, relative, "source_pack_output");
+        const previous = await ownedArtifacts(projectRoot, relative);
+        const planned = [];
+        for (const artifact of artifacts) {
+            if (normalizeRepositoryFile(artifact.name) !== artifact.name)
+                throw Error("invalid Source Pack artifact name");
+            const file = relative + "/" + artifact.name, before = await captureMutationFileState(projectRoot, file);
+            if (before.exists &&
+                artifact.name !== "source-pack-manifest.json" &&
+                previous.get(artifact.name) !== before.sha256)
+                throw Error("export_conflict:" + file + "; preserve user edits");
+            planned.push({ file, before, artifact });
+        }
+        const obsolete = [];
+        for (const [name, hash] of previous) {
+            const file = relative + "/" + name, before = await captureMutationFileState(projectRoot, file);
+            if (before.exists && before.sha256 !== hash)
+                throw Error("export_conflict:" + file + "; preserve user edits");
+            if (!artifacts.some((artifact) => artifact.name === name))
+                obsolete.push({ file, before });
+        }
+        for (const entry of planned)
+            await writeMaintenanceText(projectRoot, entry.file, entry.artifact.content, entry.before);
+        for (const entry of obsolete)
+            await removeMaintenanceFile(projectRoot, entry.file, entry.before);
+    });
+}
+// Only manifest-listed, byte-matching generated files are cleanup-owned.
+// Unlisted user files and historical directories without such a manifest remain.
+async function ownedArtifacts(root, directory) {
+    const state = await captureMutationFileState(root, directory + "/source-pack-manifest.json");
+    if (!state.exists)
+        return new Map();
+    const value = JSON.parse(Buffer.from(state.bytes_base64, "base64").toString("utf8"));
+    if (value.schema_version !== "source-pack-v1" ||
+        value.tool !== "ty-context export-context" ||
+        !Array.isArray(value.artifacts))
+        throw Error("unrecognized export manifest:" + directory);
+    const entries = new Map();
+    for (const row of value.artifacts) {
+        if (typeof row.name !== "string" ||
+            normalizeRepositoryFile(row.name) !== row.name ||
+            row.name === "source-pack-manifest.json" ||
+            !/^[0-9a-f]{64}$/.test(row.sha256) ||
+            entries.has(row.name))
+            throw Error("invalid export ownership entry:" + directory);
+        entries.set(row.name, row.sha256);
     }
-    await fs.rm(outputDir, { recursive: true, force: true });
-    await writeArtifacts(projectRoot, outputDir, artifacts);
+    return entries;
 }
 export async function pruneTimestampedExports(projectRoot, keepCount) {
-    if (!Number.isInteger(keepCount) || keepCount < 0) {
-        throw new Error("export-context --prune requires a non-negative integer");
-    }
-    const exportsRoot = path.join(projectRoot, "tmp", "ty-context", "context-exports");
-    let entries;
-    try {
-        entries = await fs.readdir(exportsRoot);
-    }
-    catch {
-        return;
-    }
-    const timestampDirs = entries
-        .filter((entry) => /^\d{8}T\d{6}Z$/.test(entry))
-        .sort()
-        .reverse();
-    for (const entry of timestampDirs.slice(keepCount)) {
-        await fs.rm(path.join(exportsRoot, entry), {
-            recursive: true,
-            force: true,
-        });
-    }
+    if (!Number.isInteger(keepCount) || keepCount < 0)
+        throw Error("export-context --prune requires a non-negative integer");
+    const root = "tmp/ty-context/context-exports";
+    await withMaintenanceLock(projectRoot, "export", async () => {
+        await assertSupportedSchema(projectRoot, "export-context");
+        const safe = await ensureSafeRepositoryDirectory(projectRoot, root, "export_prune_root");
+        const entries = (await fs.readdir(safe.absolute))
+            .filter((name) => /^\d{8}T\d{6}Z$/.test(name))
+            .sort()
+            .reverse();
+        for (const name of entries.slice(keepCount)) {
+            const relative = root + "/" + name, directory = path.join(safe.absolute, name);
+            await assertProtectedRepositoryDirectory(projectRoot, directory, "export_prune_directory");
+            const manifest = await captureMutationFileState(projectRoot, relative + "/source-pack-manifest.json");
+            if (!manifest.exists)
+                continue;
+            const owned = await ownedArtifacts(projectRoot, relative), planned = [];
+            for (const [file, hash] of owned) {
+                const before = await captureMutationFileState(projectRoot, relative + "/" + file);
+                if (before.exists && before.sha256 !== hash)
+                    throw Error("export_cleanup_conflict:" + relative + "/" + file);
+                planned.push({ file: relative + "/" + file, before });
+            }
+            for (const item of planned)
+                await removeMaintenanceFile(projectRoot, item.file, item.before);
+            await removeMaintenanceFile(projectRoot, relative + "/source-pack-manifest.json", manifest);
+            try {
+                await fs.rmdir(directory);
+            }
+            catch (error) {
+                if (error.code !== "ENOTEMPTY")
+                    throw error;
+            }
+        }
+    });
 }
 export function timestampForFile(now) {
     return now
@@ -72,17 +138,6 @@ export function timestampForFile(now) {
         .replace(/[-:]/g, "")
         .replace(/\.\d{3}Z$/, "Z");
 }
-async function writeArtifacts(projectRoot, outputDir, artifacts) {
-    for (const artifact of artifacts) {
-        const target = path.join(outputDir, ...artifact.name.split("/"));
-        const relative = repoRelative(projectRoot, target);
-        if (!relative.startsWith("tmp/ty-context/context-exports/")) {
-            throw new Error("Source Pack artifacts must stay under tmp/ty-context/context-exports/**");
-        }
-        await ensureDir(path.dirname(target));
-        await writeTextIfChanged(target, artifact.content);
-    }
-}
 async function gitInfo(projectRoot) {
     try {
         const shaResult = await execFileAsync("git", ["-C", projectRoot, "rev-parse", "HEAD"], { encoding: "utf8" });

package/dist/lib/sync-engine.d.ts

@@ -5,4 +5,10 @@ export interface SyncReport {
     notices?: string[];
 }
 export declare function emptySyncReport(): SyncReport;
-export declare function runSync(projectRoot: string): Promise<SyncReport>;
+export declare function runSync(repository: string): Promise<SyncReport>;
+export declare function syncStartupInstructions(repository: string): Promise<SyncReport>;
+export declare function prepareStartupInstructions(repository: string): Promise<{
+    before: import("./context-mutation/mutation-types.js").MutationFileState;
+    content: string | undefined;
+    blocked: string[];
+}>;