@funnelsgrove/cli 0.1.15 → 0.1.18

package/dist/docsTransaction.js

@@ -0,0 +1,1755 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { chmod, link, lstat, mkdir, open, readFile, readdir, rename, rm, unlink, } from 'node:fs/promises';
+import path from 'node:path';
+import { CURRENT_STEP_CONTRACT_VERSION, PREVIOUS_STEP_CONTRACT_VERSION, } from '@funnelsgrove/runtime';
+export const DOCS_MANIFEST_FILE = '.funnelsgrove-docs.json';
+export class DocsTransactionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'DocsTransactionError';
+        this.code = code;
+    }
+}
+const hashBytes = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const caseKey = (value) => value.normalize('NFC').toLowerCase();
+const docsError = (message) => new DocsTransactionError('FG-DOC-001', message);
+const SUPPORTED_DOCS_CONTRACT_VERSIONS = new Set([
+    PREVIOUS_STEP_CONTRACT_VERSION,
+    CURRENT_STEP_CONTRACT_VERSION,
+]);
+const assertManagedPath = (value) => {
+    if (typeof value !== 'string'
+        || value.length === 0
+        || value.includes('\\')
+        || /[\x00-\x1f\x7f]/.test(value)
+        || /^[A-Za-z]:/.test(value)) {
+        throw docsError('Managed documentation path is invalid');
+    }
+    const segments = value.split('/');
+    if (path.posix.isAbsolute(value)
+        || path.posix.normalize(value) !== value
+        || segments.some((segment) => !segment || segment === '.' || segment === '..')
+        || value === DOCS_MANIFEST_FILE
+        || segments[0] === '.funnelsgrove') {
+        throw docsError(`Unsafe managed documentation path: ${value}`);
+    }
+    return value;
+};
+const assertHash = (value, label) => {
+    if (typeof value !== 'string' || !/^[a-f0-9]{64}$/.test(value)) {
+        throw docsError(`${label} must be a lowercase SHA-256 hash`);
+    }
+    return value;
+};
+const parseManifest = (bytes, expectedContract) => {
+    let value;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw docsError('Documentation manifest is not valid JSON');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw docsError('Documentation manifest must be an object');
+    }
+    const raw = value;
+    if (raw.schemaVersion !== 1
+        || typeof raw.bundleVersion !== 'string'
+        || raw.bundleVersion.length === 0
+        || typeof raw.stepContractVersion !== 'number'
+        || !SUPPORTED_DOCS_CONTRACT_VERSIONS.has(raw.stepContractVersion)
+        || (expectedContract !== undefined && raw.stepContractVersion !== expectedContract)
+        || !Array.isArray(raw.managedFiles)) {
+        throw docsError('Unsupported documentation manifest schema or contract version');
+    }
+    assertHash(raw.contractHash, 'Contract hash');
+    const seen = new Map();
+    const managedFiles = raw.managedFiles.map((entry) => {
+        if (!entry || typeof entry !== 'object')
+            throw docsError('Invalid managed file entry');
+        const managed = entry;
+        const managedPath = assertManagedPath(managed.path);
+        const key = caseKey(managedPath);
+        const collision = seen.get(key);
+        if (collision)
+            throw docsError(`Duplicate or case-colliding paths: ${collision}, ${managedPath}`);
+        seen.set(key, managedPath);
+        return { path: managedPath, sha256: assertHash(managed.sha256, `Hash for ${managedPath}`) };
+    });
+    return {
+        schemaVersion: 1,
+        bundleVersion: raw.bundleVersion,
+        stepContractVersion: raw.stepContractVersion,
+        contractHash: raw.contractHash,
+        managedFiles,
+    };
+};
+const readOptionalFile = async (filePath) => {
+    try {
+        return await readFile(filePath);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+};
+const assertNoSymlinkPath = async (root, relativePath) => {
+    const rootInfo = await lstat(root).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (rootInfo?.isSymbolicLink())
+        throw docsError(`Symbolic link root is not allowed: ${root}`);
+    let current = root;
+    for (const segment of relativePath.split('/')) {
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        const matches = entries.filter((entry) => caseKey(entry.name) === caseKey(segment));
+        if (matches.length > 1 || (matches.length === 1 && matches[0].name !== segment)) {
+            throw docsError(`Case-colliding target path: ${relativePath}`);
+        }
+        const match = matches[0];
+        if (!match)
+            return;
+        current = path.join(current, match.name);
+        const info = await lstat(current);
+        if (info.isSymbolicLink())
+            throw docsError(`Symbolic link is not allowed: ${relativePath}`);
+    }
+};
+const readManagedTarget = async (root, relativePath) => {
+    await assertNoSymlinkPath(root, relativePath);
+    const absolutePath = path.join(root, ...relativePath.split('/'));
+    let info;
+    try {
+        info = await lstat(absolutePath);
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    if (!info.isFile())
+        throw docsError(`Managed documentation target is not a file: ${relativePath}`);
+    const bytes = await readFile(absolutePath);
+    return { bytes, mode: info.mode & 0o777, sha256: hashBytes(bytes) };
+};
+export const loadBundledDocs = async (sourceDir) => {
+    const root = path.resolve(sourceDir);
+    await assertNoSymlinkPath(root, DOCS_MANIFEST_FILE);
+    const manifestBytes = await readOptionalFile(path.join(root, DOCS_MANIFEST_FILE));
+    if (!manifestBytes)
+        throw docsError(`Missing bundled ${DOCS_MANIFEST_FILE}`);
+    const manifest = parseManifest(manifestBytes);
+    const files = new Map();
+    for (const managed of [...manifest.managedFiles].sort((a, b) => a.path.localeCompare(b.path))) {
+        const loaded = await readManagedTarget(root, managed.path);
+        if (!loaded || loaded.sha256 !== managed.sha256) {
+            throw docsError(`Bundled documentation hash mismatch: ${managed.path}`);
+        }
+        files.set(managed.path, { ...loaded, path: managed.path });
+    }
+    return { root, manifest, manifestBytes, files };
+};
+const readPriorManifest = async (targetRoot, contractVersion) => {
+    await assertNoSymlinkPath(targetRoot, DOCS_MANIFEST_FILE);
+    const bytes = await readOptionalFile(path.join(targetRoot, DOCS_MANIFEST_FILE));
+    return bytes ? parseManifest(bytes, contractVersion) : null;
+};
+export const inspectTemplateDocs = async (bundle, targetDir, options = {}) => {
+    const targetRoot = path.resolve(targetDir);
+    const priorManifest = await readPriorManifest(targetRoot, bundle.manifest.stepContractVersion);
+    const prior = new Map((priorManifest?.managedFiles ?? []).map((file) => [file.path, file.sha256]));
+    const catalog = new Map();
+    for (const entry of options.legacyCatalog ?? []) {
+        if (!entry || typeof entry.version !== 'string')
+            throw docsError('Invalid legacy docs catalog entry');
+        const catalogPath = assertManagedPath(entry.path);
+        const catalogHash = assertHash(entry.sha256, `Legacy hash for ${catalogPath}`);
+        const hashes = catalog.get(catalogPath) ?? new Set();
+        hashes.add(catalogHash);
+        catalog.set(catalogPath, hashes);
+    }
+    const authoritativeByCase = new Map();
+    for (const authoritativePath of [...bundle.files.keys(), ...prior.keys()]) {
+        const key = caseKey(authoritativePath);
+        const collision = authoritativeByCase.get(key);
+        if (collision && collision !== authoritativePath) {
+            throw docsError(`Case-colliding managed paths: ${collision}, ${authoritativePath}`);
+        }
+        authoritativeByCase.set(key, authoritativePath);
+    }
+    const relevantCatalogPaths = [...catalog.keys()].filter((catalogPath) => {
+        const authoritativePath = authoritativeByCase.get(caseKey(catalogPath));
+        return authoritativePath === undefined || authoritativePath === catalogPath;
+    });
+    const paths = new Set([...bundle.files.keys(), ...prior.keys(), ...relevantCatalogPaths]);
+    const files = [];
+    for (const relativePath of [...paths].sort((a, b) => a.localeCompare(b))) {
+        const bundled = bundle.files.get(relativePath);
+        const priorHash = prior.get(relativePath);
+        const current = await readManagedTarget(targetRoot, relativePath);
+        if (!bundled && priorHash === undefined && !current)
+            continue;
+        const base = {
+            path: relativePath,
+            ...(current ? { currentHash: current.sha256 } : {}),
+            ...(bundled ? { bundledHash: bundled.sha256 } : {}),
+            ...(priorHash === undefined ? {} : { priorHash }),
+        };
+        if (bundled) {
+            if (!current)
+                files.push({ ...base, state: 'missing' });
+            else if (current.sha256 === bundled.sha256)
+                files.push({ ...base, state: 'current' });
+            else if (priorHash !== undefined && current.sha256 === priorHash) {
+                files.push({ ...base, state: 'known-legacy-current-path' });
+            }
+            else if (priorHash === undefined && catalog.get(relativePath)?.has(current.sha256)) {
+                files.push({ ...base, state: 'known-legacy-current-path' });
+            }
+            else
+                files.push({ ...base, state: priorHash === undefined ? 'conflict' : 'changed' });
+        }
+        else if (priorHash !== undefined) {
+            files.push({
+                ...base,
+                state: !current || current.sha256 === priorHash ? 'owned-obsolete' : 'conflict',
+            });
+        }
+        else if (current) {
+            files.push({
+                ...base,
+                state: catalog.get(relativePath)?.has(current.sha256)
+                    ? 'known-legacy-obsolete'
+                    : 'conflict',
+            });
+        }
+    }
+    return { bundle, targetRoot, priorManifest, files };
+};
+const manifestsMatch = (prior, bundled) => {
+    if (!prior)
+        return false;
+    const priorFiles = prior.managedFiles
+        .map((file) => `${file.path}\0${file.sha256}`)
+        .sort();
+    const bundledFiles = bundled.managedFiles
+        .map((file) => `${file.path}\0${file.sha256}`)
+        .sort();
+    return prior.schemaVersion === bundled.schemaVersion
+        && prior.bundleVersion === bundled.bundleVersion
+        && prior.stepContractVersion === bundled.stepContractVersion
+        && prior.contractHash === bundled.contractHash
+        && JSON.stringify(priorFiles) === JSON.stringify(bundledFiles);
+};
+const actionForState = (file, prior, manifestCurrent) => {
+    switch (file.state) {
+        case 'current':
+            return manifestCurrent && prior?.managedFiles.some((managed) => managed.path === file.path && managed.sha256 === file.bundledHash) ? 'none' : 'adopt';
+        case 'missing': return 'install';
+        case 'known-legacy-current-path': return 'replace-known';
+        case 'known-legacy-obsolete': return 'retire-known';
+        case 'owned-obsolete': return 'retire-owned';
+        case 'changed':
+        case 'conflict': return 'conflict';
+    }
+};
+export const planTemplateDocsUpdate = (inspection) => {
+    const manifestCurrent = manifestsMatch(inspection.priorManifest, inspection.bundle.manifest);
+    const files = inspection.files.map((file) => ({
+        ...file,
+        action: actionForState(file, inspection.priorManifest, manifestCurrent),
+    }));
+    const diagnostics = files
+        .filter((file) => file.action === 'conflict')
+        .map((file) => ({
+        code: 'FG-DOC-002',
+        path: file.path,
+        message: `Managed documentation conflicts with local content: ${file.path}`,
+    }));
+    return {
+        bundleVersion: inspection.bundle.manifest.bundleVersion,
+        contractVersion: inspection.bundle.manifest.stepContractVersion,
+        clean: files.every((file) => file.action === 'none') && manifestCurrent,
+        files,
+        diagnostics,
+    };
+};
+const STATE_DIRECTORY = '.funnelsgrove';
+const TRANSACTION_DIRECTORY = 'docs-transaction';
+const PREPARING_DIRECTORY_PREFIX = `${TRANSACTION_DIRECTORY}-preparing-`;
+const TOMBSTONE_DIRECTORY_PREFIX = `${TRANSACTION_DIRECTORY}-tombstone-`;
+const GARBAGE_DIRECTORY_PREFIX = `${TRANSACTION_DIRECTORY}-garbage-`;
+const RECOVERY_CLAIM_NAME = 'docs-recovery-claim';
+const RECOVERY_CLAIM_PREPARING_PREFIX = `${RECOVERY_CLAIM_NAME}-preparing-`;
+const RECOVERY_CLAIM_OBSERVING_PREFIX = `${RECOVERY_CLAIM_NAME}-observing-`;
+const BACKUPS_DIRECTORY = 'docs-backups';
+const JOURNAL_FILE = 'journal.json';
+const isErrno = (error, code) => error instanceof Error && 'code' in error && error.code === code;
+const fault = async (injector, point) => {
+    await injector?.(point);
+};
+const syncDirectory = async (directory) => {
+    const handle = await open(directory, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+};
+const writeSyncedFile = async (filePath, bytes, mode) => {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const handle = await open(filePath, 'wx', mode);
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await chmod(filePath, mode);
+};
+const writeJournal = async (journalPath, journal) => {
+    const temporaryPath = `${journalPath}.tmp`;
+    await rm(temporaryPath, { force: true });
+    await writeSyncedFile(temporaryPath, Buffer.from(`${JSON.stringify(journal, null, 2)}\n`), 0o600);
+    await rename(temporaryPath, journalPath);
+    await syncDirectory(path.dirname(journalPath));
+};
+const transactionPaths = (targetRoot) => {
+    const stateRoot = path.join(targetRoot, STATE_DIRECTORY);
+    const transactionRoot = path.join(stateRoot, TRANSACTION_DIRECTORY);
+    return {
+        stateRoot,
+        transactionRoot,
+        journalPath: path.join(transactionRoot, JOURNAL_FILE),
+    };
+};
+const assertTransactionId = (value) => {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(value)) {
+        throw docsError('Invalid documentation transaction ID');
+    }
+    return value;
+};
+const assertStateDirectoriesSafe = async (targetRoot) => {
+    const rootInfo = await lstat(targetRoot).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (rootInfo?.isSymbolicLink())
+        throw docsError('Documentation target root cannot be a symlink');
+    const statePath = path.join(targetRoot, STATE_DIRECTORY);
+    const stateInfo = await lstat(statePath).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (stateInfo && (!stateInfo.isDirectory() || stateInfo.isSymbolicLink())) {
+        throw docsError(`${STATE_DIRECTORY} must be a real directory`);
+    }
+    const backupsPath = path.join(statePath, BACKUPS_DIRECTORY);
+    const backupsInfo = await lstat(backupsPath).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (backupsInfo && (!backupsInfo.isDirectory() || backupsInfo.isSymbolicLink())) {
+        throw docsError(`${STATE_DIRECTORY}/${BACKUPS_DIRECTORY} must be a real directory`);
+    }
+};
+const artifactInfo = async (absolutePath) => {
+    let info;
+    try {
+        info = await lstat(absolutePath);
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return null;
+        throw error;
+    }
+    if (!info.isFile() || info.isSymbolicLink())
+        return null;
+    const bytes = await readFile(absolutePath);
+    return { bytes, hash: hashBytes(bytes), mode: info.mode & 0o777 };
+};
+const hashMatches = async (absolutePath, expected) => (await artifactInfo(absolutePath))?.hash === expected;
+const relativeBackupPath = (transactionId, relativePath) => `${STATE_DIRECTORY}/${BACKUPS_DIRECTORY}/${transactionId}/${relativePath}`;
+const absoluteTargetPath = (targetRoot, relativePath) => path.join(targetRoot, ...relativePath.split('/'));
+const absoluteTransactionPath = (transactionRoot, relativePath) => path.join(transactionRoot, ...relativePath.split('/'));
+const beforeMatches = (current, operation) => current?.sha256 === operation.beforeHash || (!current && operation.beforeHash === null);
+const afterMatches = (current, operation) => current?.sha256 === operation.afterHash || (!current && operation.afterHash === null);
+const createOperation = async (bundle, targetRoot, file, transactionId) => {
+    const current = await readManagedTarget(targetRoot, file.path);
+    const bundled = bundle.files.get(file.path);
+    const backupPath = current ? relativeBackupPath(transactionId, file.path) : null;
+    if (file.action === 'install') {
+        if (current || !bundled || file.bundledHash !== bundled.sha256) {
+            throw docsError(`Documentation plan is stale for ${file.path}`);
+        }
+        return {
+            operation: {
+                action: 'install',
+                path: file.path,
+                beforeHash: null,
+                afterHash: bundled.sha256,
+                stagedPath: `staged/${file.path}`,
+                backupPath: null,
+                beforeMode: null,
+                afterMode: bundled.mode,
+                applied: false,
+            },
+            bytes: bundled.bytes,
+        };
+    }
+    if (file.action === 'replace-known') {
+        if (!current || !bundled || current.sha256 !== file.currentHash || file.bundledHash !== bundled.sha256) {
+            throw docsError(`Documentation plan is stale for ${file.path}`);
+        }
+        return {
+            operation: {
+                action: 'replace-known',
+                path: file.path,
+                beforeHash: current.sha256,
+                afterHash: bundled.sha256,
+                stagedPath: `staged/${file.path}`,
+                backupPath,
+                beforeMode: current.mode,
+                afterMode: current.mode,
+                applied: false,
+            },
+            bytes: bundled.bytes,
+        };
+    }
+    if (file.action === 'retire-known' || file.action === 'retire-owned') {
+        if (!current)
+            return null;
+        if (current.sha256 !== file.currentHash)
+            throw docsError(`Documentation plan is stale for ${file.path}`);
+        return {
+            operation: {
+                action: file.action,
+                path: file.path,
+                beforeHash: current.sha256,
+                afterHash: null,
+                stagedPath: null,
+                backupPath,
+                beforeMode: current.mode,
+                afterMode: null,
+                applied: false,
+            },
+        };
+    }
+    return null;
+};
+const prepareTransaction = async (bundle, targetRoot, status, options, selectedConflict) => {
+    await mkdir(targetRoot, { recursive: true });
+    await assertStateDirectoriesSafe(targetRoot);
+    const { stateRoot, transactionRoot } = transactionPaths(targetRoot);
+    await mkdir(stateRoot, { recursive: true });
+    await mkdir(path.join(stateRoot, BACKUPS_DIRECTORY), { recursive: true });
+    const transactionId = assertTransactionId(options.transactionId ?? randomUUID());
+    const preparingRoot = path.join(stateRoot, `${PREPARING_DIRECTORY_PREFIX}${process.pid}-${transactionId}`);
+    const preparingJournalPath = path.join(preparingRoot, JOURNAL_FILE);
+    try {
+        await mkdir(preparingRoot);
+    }
+    catch (error) {
+        if (isErrno(error, 'EEXIST')) {
+            throw new DocsTransactionError('FG-DOC-CONCURRENT', 'A documentation transaction is already being prepared');
+        }
+        throw error;
+    }
+    const operationBytes = new Map();
+    const operations = [];
+    let activated = false;
+    try {
+        if (selectedConflict) {
+            const current = await readManagedTarget(targetRoot, selectedConflict.path);
+            const bundled = bundle.files.get(selectedConflict.path);
+            if (!current || !bundled || current.sha256 !== selectedConflict.currentHash) {
+                throw docsError(`Documentation conflict changed before replacement: ${selectedConflict.path}`);
+            }
+            operations.push({
+                action: 'replace-managed',
+                path: selectedConflict.path,
+                beforeHash: current.sha256,
+                afterHash: bundled.sha256,
+                stagedPath: `staged/${selectedConflict.path}`,
+                backupPath: relativeBackupPath(transactionId, selectedConflict.path),
+                beforeMode: current.mode,
+                afterMode: current.mode,
+                applied: false,
+            });
+            operationBytes.set(selectedConflict.path, bundled.bytes);
+        }
+        else {
+            for (const file of status.files) {
+                const prepared = await createOperation(bundle, targetRoot, file, transactionId);
+                if (!prepared)
+                    continue;
+                operations.push(prepared.operation);
+                if (prepared.bytes)
+                    operationBytes.set(file.path, prepared.bytes);
+            }
+        }
+        let manifest = null;
+        let manifestBytes = null;
+        if (!selectedConflict) {
+            const currentManifest = await readManagedTarget(targetRoot, DOCS_MANIFEST_FILE);
+            manifestBytes = bundle.manifestBytes;
+            manifest = {
+                path: DOCS_MANIFEST_FILE,
+                beforeHash: currentManifest?.sha256 ?? null,
+                afterHash: hashBytes(manifestBytes),
+                stagedPath: `staged/${DOCS_MANIFEST_FILE}`,
+                backupPath: currentManifest ? relativeBackupPath(transactionId, DOCS_MANIFEST_FILE) : null,
+                beforeMode: currentManifest?.mode ?? null,
+                afterMode: currentManifest?.mode ?? 0o644,
+            };
+        }
+        const journal = {
+            schemaVersion: 1,
+            transactionId,
+            ownerPid: process.pid,
+            phase: 'prepared',
+            targetRoot,
+            operations: operations.sort((left, right) => left.path.localeCompare(right.path)),
+            manifest,
+        };
+        await writeJournal(preparingJournalPath, journal);
+        try {
+            await rename(preparingRoot, transactionRoot);
+        }
+        catch (error) {
+            if (isErrno(error, 'EEXIST') || isErrno(error, 'ENOTEMPTY')) {
+                throw new DocsTransactionError('FG-DOC-CONCURRENT', 'An unfinished documentation transaction already exists');
+            }
+            throw error;
+        }
+        activated = true;
+        await syncDirectory(stateRoot);
+        return {
+            journal,
+            transactionRoot,
+            journalPath: path.join(transactionRoot, JOURNAL_FILE),
+            operationBytes,
+            manifestBytes,
+        };
+    }
+    catch (error) {
+        if (!activated)
+            await rm(preparingRoot, { recursive: true, force: true });
+        throw error;
+    }
+};
+const stagedArtifacts = (prepared) => {
+    const artifacts = prepared.journal.operations.flatMap((operation) => {
+        if (!operation.stagedPath || operation.afterMode === null)
+            return [];
+        const bytes = prepared.operationBytes.get(operation.path);
+        if (!bytes)
+            throw docsError(`Missing staged bytes for ${operation.path}`);
+        return [{
+                relativePath: operation.path,
+                path: operation.stagedPath,
+                bytes,
+                mode: operation.afterMode,
+            }];
+    });
+    if (prepared.journal.manifest && prepared.manifestBytes) {
+        artifacts.push({
+            relativePath: DOCS_MANIFEST_FILE,
+            path: prepared.journal.manifest.stagedPath,
+            bytes: prepared.manifestBytes,
+            mode: prepared.journal.manifest.afterMode,
+        });
+    }
+    return artifacts;
+};
+const backupArtifacts = async (prepared) => {
+    const artifacts = [];
+    for (const operation of prepared.journal.operations) {
+        if (!operation.backupPath || operation.beforeHash === null || operation.beforeMode === null)
+            continue;
+        const current = await readManagedTarget(prepared.journal.targetRoot, operation.path);
+        if (!current || current.sha256 !== operation.beforeHash) {
+            throw docsError(`Documentation target changed while preparing: ${operation.path}`);
+        }
+        artifacts.push({
+            relativePath: operation.path,
+            path: operation.backupPath,
+            bytes: current.bytes,
+            mode: operation.beforeMode,
+        });
+    }
+    const manifest = prepared.journal.manifest;
+    if (manifest?.backupPath && manifest.beforeHash !== null && manifest.beforeMode !== null) {
+        const current = await readManagedTarget(prepared.journal.targetRoot, DOCS_MANIFEST_FILE);
+        if (!current || current.sha256 !== manifest.beforeHash) {
+            throw docsError(`Documentation target changed while preparing: ${DOCS_MANIFEST_FILE}`);
+        }
+        artifacts.push({
+            relativePath: DOCS_MANIFEST_FILE,
+            path: manifest.backupPath,
+            bytes: current.bytes,
+            mode: manifest.beforeMode,
+        });
+    }
+    return artifacts;
+};
+const writeArtifactTemps = async (root, artifacts) => {
+    for (const artifact of artifacts) {
+        const finalPath = absoluteTransactionPath(root, artifact.path);
+        await writeSyncedFile(`${finalPath}.tmp`, artifact.bytes, artifact.mode);
+    }
+};
+const finalizeArtifacts = async (root, artifacts, operation, injector) => {
+    for (const artifact of artifacts) {
+        const finalPath = absoluteTransactionPath(root, artifact.path);
+        await fault(injector, { operation, timing: 'before', path: artifact.relativePath });
+        await rename(`${finalPath}.tmp`, finalPath);
+        await syncDirectory(path.dirname(finalPath));
+        await fault(injector, { operation, timing: 'after', path: artifact.relativePath });
+    }
+};
+const prepareArtifacts = async (prepared, injector) => {
+    const stages = stagedArtifacts(prepared);
+    await writeArtifactTemps(prepared.transactionRoot, stages);
+    await finalizeArtifacts(prepared.transactionRoot, stages, 'stage', injector);
+    const backups = await backupArtifacts(prepared);
+    await writeArtifactTemps(prepared.journal.targetRoot, backups);
+    await finalizeArtifacts(prepared.journal.targetRoot, backups, 'backup', injector);
+};
+const assertJournalArtifactPathsSafe = async (transactionRoot, journal) => {
+    for (const operation of journal.operations) {
+        if (operation.stagedPath) {
+            await assertNoSymlinkPath(transactionRoot, operation.stagedPath);
+            await assertNoSymlinkPath(transactionRoot, `${operation.stagedPath}.tmp`);
+        }
+        await assertNoSymlinkPath(transactionRoot, `retired/${operation.path}`);
+        if (operation.backupPath) {
+            await assertNoSymlinkPath(journal.targetRoot, operation.backupPath);
+            await assertNoSymlinkPath(journal.targetRoot, `${operation.backupPath}.tmp`);
+        }
+    }
+    const manifest = journal.manifest;
+    if (manifest) {
+        await assertNoSymlinkPath(transactionRoot, manifest.stagedPath);
+        await assertNoSymlinkPath(transactionRoot, `${manifest.stagedPath}.tmp`);
+        if (manifest.backupPath) {
+            await assertNoSymlinkPath(journal.targetRoot, manifest.backupPath);
+            await assertNoSymlinkPath(journal.targetRoot, `${manifest.backupPath}.tmp`);
+        }
+    }
+};
+const assertTargetHash = async (targetRoot, operation) => {
+    const current = await readManagedTarget(targetRoot, operation.path);
+    if (!beforeMatches(current, operation) && !afterMatches(current, operation)) {
+        throw new DocsTransactionError('FG-DOC-RECOVERY', `Unexpected documentation target while applying: ${operation.path}`);
+    }
+    return current;
+};
+const applyOperation = async (transactionRoot, journalPath, journal, operation, injector) => {
+    const targetRoot = journal.targetRoot;
+    const current = await assertTargetHash(targetRoot, operation);
+    if (afterMatches(current, operation)) {
+        operation.applied = true;
+        await writeJournal(journalPath, journal);
+        return;
+    }
+    const targetPath = absoluteTargetPath(targetRoot, operation.path);
+    await assertNoSymlinkPath(targetRoot, operation.path);
+    if (operation.afterHash === null) {
+        const retiredPath = absoluteTransactionPath(transactionRoot, `retired/${operation.path}`);
+        await mkdir(path.dirname(retiredPath), { recursive: true });
+        await fault(injector, { operation: 'apply', timing: 'before', path: operation.path });
+        const latest = await assertTargetHash(targetRoot, operation);
+        if (afterMatches(latest, operation)) {
+            operation.applied = true;
+            await writeJournal(journalPath, journal);
+            return;
+        }
+        await rename(targetPath, retiredPath);
+    }
+    else {
+        if (!operation.stagedPath)
+            throw docsError(`Missing staged path for ${operation.path}`);
+        const stagedPath = absoluteTransactionPath(transactionRoot, operation.stagedPath);
+        if (!(await hashMatches(stagedPath, operation.afterHash))) {
+            throw new DocsTransactionError('FG-DOC-RECOVERY', `Invalid staged file: ${operation.path}`);
+        }
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        await fault(injector, { operation: 'apply', timing: 'before', path: operation.path });
+        const latest = await assertTargetHash(targetRoot, operation);
+        if (afterMatches(latest, operation)) {
+            operation.applied = true;
+            await writeJournal(journalPath, journal);
+            return;
+        }
+        await rename(stagedPath, targetPath);
+        if (operation.afterMode !== null)
+            await chmod(targetPath, operation.afterMode);
+    }
+    await syncDirectory(path.dirname(targetPath));
+    await fault(injector, { operation: 'apply', timing: 'after', path: operation.path });
+    operation.applied = true;
+    await writeJournal(journalPath, journal);
+};
+const moveStateDirectoryToGarbage = async (stateRoot, sourcePath) => {
+    const garbagePath = path.join(stateRoot, `${GARBAGE_DIRECTORY_PREFIX}${randomUUID()}`);
+    try {
+        await rename(sourcePath, garbagePath);
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return false;
+        throw error;
+    }
+    await syncDirectory(stateRoot);
+    await rm(garbagePath, { recursive: true, force: true });
+    await syncDirectory(stateRoot);
+    return true;
+};
+const removeTransaction = async (transactionRoot, journal) => {
+    const stateRoot = path.dirname(transactionRoot);
+    const tombstonePath = path.join(stateRoot, `${TOMBSTONE_DIRECTORY_PREFIX}${journal.transactionId}`);
+    const existingTombstone = await lstat(tombstonePath).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (existingTombstone) {
+        throw recoveryError(`Documentation transaction tombstone already exists: ${journal.transactionId}`);
+    }
+    await rename(transactionRoot, tombstonePath);
+    await syncDirectory(stateRoot);
+    if (!(await moveStateDirectoryToGarbage(stateRoot, tombstonePath))) {
+        throw recoveryError(`Documentation transaction tombstone disappeared: ${journal.transactionId}`);
+    }
+};
+const commitManifest = async (transactionRoot, journalPath, journal, injector) => {
+    const assertAppliedTargetsMatch = async () => {
+        for (const operation of journal.operations) {
+            const current = await readManagedTarget(journal.targetRoot, operation.path);
+            if (!operation.applied || !afterMatches(current, operation)) {
+                throw new DocsTransactionError('FG-DOC-RECOVERY', `Documentation target changed before manifest commit: ${operation.path}`);
+            }
+        }
+    };
+    const manifest = journal.manifest;
+    if (!manifest) {
+        await assertAppliedTargetsMatch();
+        await removeTransaction(transactionRoot, journal);
+        return;
+    }
+    journal.phase = 'manifest-pending';
+    await writeJournal(journalPath, journal);
+    let current = await readManagedTarget(journal.targetRoot, DOCS_MANIFEST_FILE);
+    if (current?.sha256 === manifest.afterHash) {
+        await assertAppliedTargetsMatch();
+        await removeTransaction(transactionRoot, journal);
+        return;
+    }
+    if (current?.sha256 !== manifest.beforeHash && !(current === null && manifest.beforeHash === null)) {
+        throw new DocsTransactionError('FG-DOC-RECOVERY', 'Unexpected documentation manifest');
+    }
+    const stagedPath = absoluteTransactionPath(transactionRoot, manifest.stagedPath);
+    if (!(await hashMatches(stagedPath, manifest.afterHash))) {
+        throw new DocsTransactionError('FG-DOC-RECOVERY', 'Invalid staged documentation manifest');
+    }
+    const targetPath = path.join(journal.targetRoot, DOCS_MANIFEST_FILE);
+    await fault(injector, { operation: 'manifest', timing: 'before', path: DOCS_MANIFEST_FILE });
+    await assertAppliedTargetsMatch();
+    if (!(await hashMatches(stagedPath, manifest.afterHash))) {
+        throw new DocsTransactionError('FG-DOC-RECOVERY', 'Invalid staged documentation manifest');
+    }
+    current = await readManagedTarget(journal.targetRoot, DOCS_MANIFEST_FILE);
+    if (current?.sha256 === manifest.afterHash) {
+        await removeTransaction(transactionRoot, journal);
+        return;
+    }
+    if (current?.sha256 !== manifest.beforeHash && !(current === null && manifest.beforeHash === null)) {
+        throw new DocsTransactionError('FG-DOC-RECOVERY', 'Unexpected documentation manifest');
+    }
+    await rename(stagedPath, targetPath);
+    await chmod(targetPath, manifest.afterMode);
+    await syncDirectory(journal.targetRoot);
+    await fault(injector, { operation: 'manifest', timing: 'after', path: DOCS_MANIFEST_FILE });
+    await removeTransaction(transactionRoot, journal);
+};
+const executePreparedTransaction = async (prepared, injector) => {
+    await assertJournalArtifactPathsSafe(prepared.transactionRoot, prepared.journal);
+    await prepareArtifacts(prepared, injector);
+    prepared.journal.phase = 'applying';
+    await writeJournal(prepared.journalPath, prepared.journal);
+    for (const operation of prepared.journal.operations) {
+        await applyOperation(prepared.transactionRoot, prepared.journalPath, prepared.journal, operation, injector);
+    }
+    await commitManifest(prepared.transactionRoot, prepared.journalPath, prepared.journal, injector);
+};
+const relinquishTransactionOwnership = async (prepared) => {
+    const stateRoot = path.dirname(prepared.transactionRoot);
+    const tombstonePath = path.join(stateRoot, `${TOMBSTONE_DIRECTORY_PREFIX}${prepared.journal.transactionId}`);
+    for (const transactionPath of [prepared.transactionRoot, tombstonePath]) {
+        const info = await lstat(transactionPath).catch((error) => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (!info)
+            continue;
+        if (!info.isDirectory() || info.isSymbolicLink()) {
+            throw recoveryError('Cannot safely relinquish documentation transaction ownership');
+        }
+        prepared.journal.ownerPid = null;
+        await writeJournal(path.join(transactionPath, JOURNAL_FILE), prepared.journal);
+        return;
+    }
+};
+const executeOwnedTransaction = async (prepared, injector) => {
+    try {
+        await executePreparedTransaction(prepared, injector);
+    }
+    catch (error) {
+        await relinquishTransactionOwnership(prepared);
+        throw error;
+    }
+};
+const assertNoOpenTransaction = async (targetRoot) => {
+    const { stateRoot, transactionRoot } = transactionPaths(targetRoot);
+    const existing = await lstat(transactionRoot).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (existing) {
+        throw new DocsTransactionError('FG-DOC-CONCURRENT', 'An unfinished documentation transaction already exists');
+    }
+    const residue = (await listStateEntries(stateRoot)).find((entry) => entry.startsWith(PREPARING_DIRECTORY_PREFIX)
+        || entry.startsWith(TOMBSTONE_DIRECTORY_PREFIX)
+        || entry.startsWith(GARBAGE_DIRECTORY_PREFIX)
+        || entry.startsWith(RECOVERY_CLAIM_PREPARING_PREFIX)
+        || entry.startsWith(RECOVERY_CLAIM_OBSERVING_PREFIX)
+        || entry === RECOVERY_CLAIM_NAME);
+    if (residue) {
+        throw new DocsTransactionError('FG-DOC-CONCURRENT', `Documentation transaction recovery is required before continuing: ${residue}`);
+    }
+};
+const validateStatus = (bundle, status) => {
+    if (status.bundleVersion !== bundle.manifest.bundleVersion
+        || status.contractVersion !== bundle.manifest.stepContractVersion) {
+        throw docsError('Documentation status does not match the bundled documentation');
+    }
+    const seen = new Set();
+    for (const file of status.files) {
+        assertManagedPath(file.path);
+        const key = caseKey(file.path);
+        if (seen.has(key))
+            throw docsError(`Duplicate documentation status path: ${file.path}`);
+        seen.add(key);
+    }
+};
+const docsStatusSignature = (status) => JSON.stringify({
+    bundleVersion: status.bundleVersion,
+    contractVersion: status.contractVersion,
+    clean: status.clean,
+    files: [...status.files].sort((left, right) => left.path.localeCompare(right.path)),
+    diagnostics: [...status.diagnostics].sort((left, right) => left.code.localeCompare(right.code)
+        || (left.path ?? '').localeCompare(right.path ?? '')
+        || left.message.localeCompare(right.message)),
+});
+export const applyTemplateDocsUpdate = async (bundle, targetDir, status, options = {}) => {
+    const targetRoot = path.resolve(targetDir);
+    await assertNoOpenTransaction(targetRoot);
+    validateStatus(bundle, status);
+    const currentStatus = planTemplateDocsUpdate(await inspectTemplateDocs(bundle, targetRoot, {
+        legacyCatalog: options.legacyCatalog,
+    }));
+    if (docsStatusSignature(status) !== docsStatusSignature(currentStatus)) {
+        throw docsError('Documentation update plan is stale or was not produced by current inspection');
+    }
+    if (currentStatus.files.some((file) => file.action === 'conflict')) {
+        throw new DocsTransactionError('FG-DOC-002', 'Documentation conflicts must be resolved explicitly');
+    }
+    if (currentStatus.clean)
+        return;
+    const prepared = await prepareTransaction(bundle, targetRoot, currentStatus, options);
+    await executeOwnedTransaction(prepared, options.faultInjector);
+};
+const recoveryError = (message) => new DocsTransactionError('FG-DOC-RECOVERY', message);
+const parseNullableHash = (value, label) => {
+    if (value === null)
+        return null;
+    try {
+        return assertHash(value, label);
+    }
+    catch {
+        throw recoveryError(`Corrupt journal ${label}`);
+    }
+};
+const parseNullableMode = (value, label) => {
+    if (value === null)
+        return null;
+    if (!Number.isInteger(value) || value < 0 || value > 0o777) {
+        throw recoveryError(`Corrupt journal ${label}`);
+    }
+    return value;
+};
+const parseJournal = (bytes, expectedTargetRoot) => {
+    let value;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw recoveryError('Documentation transaction journal is corrupt');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw recoveryError('Documentation transaction journal is corrupt');
+    }
+    const raw = value;
+    if (raw.schemaVersion !== 1
+        || typeof raw.transactionId !== 'string'
+        || !['prepared', 'applying', 'manifest-pending', 'restoring'].includes(String(raw.phase))
+        || raw.targetRoot !== expectedTargetRoot
+        || !Array.isArray(raw.operations)) {
+        throw recoveryError('Unsupported or mismatched documentation transaction journal');
+    }
+    let transactionId;
+    try {
+        transactionId = assertTransactionId(raw.transactionId);
+    }
+    catch {
+        throw recoveryError('Invalid documentation transaction ID in journal');
+    }
+    const ownerPid = raw.ownerPid === null
+        ? null
+        : Number.isSafeInteger(raw.ownerPid) && raw.ownerPid > 0
+            ? raw.ownerPid
+            : undefined;
+    if (ownerPid === undefined) {
+        throw recoveryError('Invalid documentation transaction owner in journal');
+    }
+    const seen = new Set();
+    const allowedActions = new Set([
+        'install',
+        'replace-known',
+        'replace-managed',
+        'retire-known',
+        'retire-owned',
+    ]);
+    const operations = raw.operations.map((entry, index) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            throw recoveryError(`Corrupt journal operation ${index}`);
+        }
+        const operation = entry;
+        let operationPath;
+        try {
+            operationPath = assertManagedPath(operation.path);
+        }
+        catch {
+            throw recoveryError(`Unsafe journal operation path at index ${index}`);
+        }
+        const key = caseKey(operationPath);
+        if (seen.has(key))
+            throw recoveryError(`Duplicate journal operation path: ${operationPath}`);
+        seen.add(key);
+        if (!allowedActions.has(operation.action) || typeof operation.applied !== 'boolean') {
+            throw recoveryError(`Corrupt journal operation ${operationPath}`);
+        }
+        const beforeHash = parseNullableHash(operation.beforeHash, `${operationPath} beforeHash`);
+        const afterHash = parseNullableHash(operation.afterHash, `${operationPath} afterHash`);
+        const beforeMode = parseNullableMode(operation.beforeMode, `${operationPath} beforeMode`);
+        const afterMode = parseNullableMode(operation.afterMode, `${operationPath} afterMode`);
+        const action = operation.action;
+        const hasBefore = [
+            beforeHash !== null,
+            beforeMode !== null,
+            operation.backupPath != null,
+        ];
+        const hasAfter = [
+            afterHash !== null,
+            afterMode !== null,
+            operation.stagedPath != null,
+        ];
+        const allBefore = hasBefore.every(Boolean);
+        const noBefore = hasBefore.every((present) => !present);
+        const allAfter = hasAfter.every(Boolean);
+        const noAfter = hasAfter.every((present) => !present);
+        const validSemantics = action === 'install'
+            ? noBefore && allAfter
+            : action === 'replace-known' || action === 'replace-managed'
+                ? allBefore && allAfter && beforeHash !== afterHash
+                : allBefore && noAfter;
+        if (!validSemantics) {
+            throw recoveryError(`Corrupt journal operation semantics for ${operationPath}`);
+        }
+        const expectedStaged = afterHash === null ? null : `staged/${operationPath}`;
+        const expectedBackup = beforeHash === null
+            ? null
+            : relativeBackupPath(transactionId, operationPath);
+        if (operation.stagedPath !== expectedStaged || operation.backupPath !== expectedBackup) {
+            throw recoveryError(`Corrupt journal artifact path for ${operationPath}`);
+        }
+        return {
+            action,
+            path: operationPath,
+            beforeHash,
+            afterHash,
+            stagedPath: expectedStaged,
+            backupPath: expectedBackup,
+            beforeMode,
+            afterMode,
+            applied: operation.applied,
+        };
+    });
+    let manifest = null;
+    if (raw.manifest !== null) {
+        if (!raw.manifest || typeof raw.manifest !== 'object' || Array.isArray(raw.manifest)) {
+            throw recoveryError('Corrupt journal manifest operation');
+        }
+        const entry = raw.manifest;
+        const beforeHash = parseNullableHash(entry.beforeHash, 'manifest beforeHash');
+        const afterHash = parseNullableHash(entry.afterHash, 'manifest afterHash');
+        const beforeMode = parseNullableMode(entry.beforeMode, 'manifest beforeMode');
+        const afterMode = parseNullableMode(entry.afterMode, 'manifest afterMode');
+        const beforePresence = [
+            beforeHash !== null,
+            beforeMode !== null,
+            entry.backupPath != null,
+        ];
+        const beforeSemanticsValid = beforePresence.every(Boolean)
+            || beforePresence.every((present) => !present);
+        const afterSemanticsValid = afterHash !== null
+            && afterMode !== null
+            && entry.stagedPath != null;
+        if (!beforeSemanticsValid || !afterSemanticsValid) {
+            throw recoveryError('Corrupt journal manifest semantics');
+        }
+        const expectedBackup = beforeHash === null
+            ? null
+            : relativeBackupPath(transactionId, DOCS_MANIFEST_FILE);
+        if (entry.path !== DOCS_MANIFEST_FILE
+            || afterHash === null
+            || afterMode === null
+            || entry.stagedPath !== `staged/${DOCS_MANIFEST_FILE}`
+            || entry.backupPath !== expectedBackup) {
+            throw recoveryError('Corrupt journal manifest operation');
+        }
+        manifest = {
+            path: DOCS_MANIFEST_FILE,
+            beforeHash,
+            afterHash,
+            stagedPath: `staged/${DOCS_MANIFEST_FILE}`,
+            backupPath: expectedBackup,
+            beforeMode,
+            afterMode,
+        };
+    }
+    const conflictReplacement = manifest === null
+        && operations.length === 1
+        && operations[0].action === 'replace-managed';
+    const normalUpdate = manifest !== null
+        && operations.every((operation) => operation.action !== 'replace-managed');
+    if (!conflictReplacement && !normalUpdate) {
+        throw recoveryError('Corrupt journal transaction semantics');
+    }
+    if (raw.phase === 'prepared' && operations.some((operation) => operation.applied)) {
+        throw recoveryError('Corrupt journal phase semantics');
+    }
+    if (raw.phase === 'manifest-pending'
+        && (manifest === null || operations.some((operation) => !operation.applied))) {
+        throw recoveryError('Corrupt journal phase semantics');
+    }
+    return {
+        schemaVersion: 1,
+        transactionId,
+        ownerPid,
+        phase: raw.phase,
+        targetRoot: expectedTargetRoot,
+        operations,
+        manifest,
+    };
+};
+const artifactOrTemporaryMatches = async (absolutePath, expectedHash) => await hashMatches(absolutePath, expectedHash)
+    || await hashMatches(`${absolutePath}.tmp`, expectedHash);
+const ensureArtifactFinal = async (absolutePath, expectedHash) => {
+    if (await hashMatches(absolutePath, expectedHash))
+        return;
+    const temporaryPath = `${absolutePath}.tmp`;
+    if (!(await hashMatches(temporaryPath, expectedHash))) {
+        throw recoveryError(`Missing or invalid transaction artifact: ${absolutePath}`);
+    }
+    await rename(temporaryPath, absolutePath);
+    await syncDirectory(path.dirname(absolutePath));
+};
+const readManifestTarget = async (targetRoot) => readManagedTarget(targetRoot, DOCS_MANIFEST_FILE);
+const canRecoverForward = async (transactionRoot, journal) => {
+    for (const operation of journal.operations) {
+        const current = await readManagedTarget(journal.targetRoot, operation.path);
+        if (operation.applied && !afterMatches(current, operation))
+            return false;
+        if (afterMatches(current, operation)) {
+            if (operation.beforeHash !== null
+                && operation.backupPath
+                && !(await artifactOrTemporaryMatches(absoluteTargetPath(journal.targetRoot, operation.backupPath), operation.beforeHash)))
+                return false;
+            continue;
+        }
+        if (!beforeMatches(current, operation))
+            return false;
+        if (operation.afterHash !== null
+            && operation.stagedPath
+            && !(await artifactOrTemporaryMatches(absoluteTransactionPath(transactionRoot, operation.stagedPath), operation.afterHash)))
+            return false;
+    }
+    const manifest = journal.manifest;
+    if (manifest) {
+        const current = await readManifestTarget(journal.targetRoot);
+        if (current?.sha256 === manifest.afterHash) {
+            if (manifest.beforeHash !== null
+                && manifest.backupPath
+                && !(await artifactOrTemporaryMatches(absoluteTargetPath(journal.targetRoot, manifest.backupPath), manifest.beforeHash)))
+                return false;
+        }
+        else {
+            if (current?.sha256 !== manifest.beforeHash && !(current === null && manifest.beforeHash === null)) {
+                return false;
+            }
+            if (!(await artifactOrTemporaryMatches(absoluteTransactionPath(transactionRoot, manifest.stagedPath), manifest.afterHash)))
+                return false;
+        }
+    }
+    return true;
+};
+const backupMatches = async (targetRoot, backupPath, beforeHash) => beforeHash === null || Boolean(backupPath
+    && await artifactOrTemporaryMatches(absoluteTargetPath(targetRoot, backupPath), beforeHash));
+const canRestore = async (journal) => {
+    for (const operation of journal.operations) {
+        const current = await readManagedTarget(journal.targetRoot, operation.path);
+        if (beforeMatches(current, operation))
+            continue;
+        if (!afterMatches(current, operation))
+            return false;
+        if (!(await backupMatches(journal.targetRoot, operation.backupPath, operation.beforeHash))) {
+            return false;
+        }
+    }
+    const manifest = journal.manifest;
+    if (manifest) {
+        const current = await readManifestTarget(journal.targetRoot);
+        if (current?.sha256 === manifest.beforeHash || (current === null && manifest.beforeHash === null)) {
+            return true;
+        }
+        if (current?.sha256 !== manifest.afterHash)
+            return false;
+        return backupMatches(journal.targetRoot, manifest.backupPath, manifest.beforeHash);
+    }
+    return true;
+};
+const ensureBackup = async (journal, relativePath, backupPath, beforeHash, beforeMode) => {
+    if (beforeHash === null || !backupPath || beforeMode === null)
+        return;
+    const absoluteBackup = absoluteTargetPath(journal.targetRoot, backupPath);
+    if (await artifactOrTemporaryMatches(absoluteBackup, beforeHash)) {
+        await ensureArtifactFinal(absoluteBackup, beforeHash);
+        return;
+    }
+    const current = await readManagedTarget(journal.targetRoot, relativePath);
+    if (!current || current.sha256 !== beforeHash) {
+        throw recoveryError(`Cannot recreate documentation backup: ${relativePath}`);
+    }
+    await writeSyncedFile(`${absoluteBackup}.tmp`, current.bytes, beforeMode);
+    await ensureArtifactFinal(absoluteBackup, beforeHash);
+};
+const continueForward = async (transactionRoot, journalPath, journal) => {
+    for (const operation of journal.operations) {
+        await ensureBackup(journal, operation.path, operation.backupPath, operation.beforeHash, operation.beforeMode);
+        const current = await readManagedTarget(journal.targetRoot, operation.path);
+        if (!afterMatches(current, operation)
+            && operation.afterHash !== null
+            && operation.stagedPath) {
+            await ensureArtifactFinal(absoluteTransactionPath(transactionRoot, operation.stagedPath), operation.afterHash);
+        }
+    }
+    const manifest = journal.manifest;
+    if (manifest) {
+        await ensureBackup(journal, DOCS_MANIFEST_FILE, manifest.backupPath, manifest.beforeHash, manifest.beforeMode);
+        const current = await readManifestTarget(journal.targetRoot);
+        if (current?.sha256 !== manifest.afterHash) {
+            await ensureArtifactFinal(absoluteTransactionPath(transactionRoot, manifest.stagedPath), manifest.afterHash);
+        }
+    }
+    journal.phase = 'applying';
+    await writeJournal(journalPath, journal);
+    for (const operation of journal.operations) {
+        await applyOperation(transactionRoot, journalPath, journal, operation);
+    }
+    await commitManifest(transactionRoot, journalPath, journal);
+};
+const restoreOne = async (journal, relativePath, beforeHash, beforeMode, afterHash, backupPath) => {
+    const current = await readManagedTarget(journal.targetRoot, relativePath);
+    if (current?.sha256 === beforeHash || (!current && beforeHash === null))
+        return;
+    if (current?.sha256 !== afterHash && !(!current && afterHash === null)) {
+        throw recoveryError(`Cannot safely restore unexpected target: ${relativePath}`);
+    }
+    const targetPath = absoluteTargetPath(journal.targetRoot, relativePath);
+    if (beforeHash === null) {
+        await rm(targetPath, { force: true });
+    }
+    else {
+        if (!backupPath || beforeMode === null)
+            throw recoveryError(`Missing backup: ${relativePath}`);
+        const backup = absoluteTargetPath(journal.targetRoot, backupPath);
+        await ensureArtifactFinal(backup, beforeHash);
+        const contents = await artifactInfo(backup);
+        if (!contents || contents.hash !== beforeHash)
+            throw recoveryError(`Invalid backup: ${relativePath}`);
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        const temporaryTarget = `${targetPath}.docs-restore-${journal.transactionId}`;
+        await rm(temporaryTarget, { force: true });
+        await writeSyncedFile(temporaryTarget, contents.bytes, beforeMode);
+        await rename(temporaryTarget, targetPath);
+        await chmod(targetPath, beforeMode);
+    }
+    await syncDirectory(path.dirname(targetPath));
+};
+const restorePriorGeneration = async (transactionRoot, journalPath, journal) => {
+    journal.phase = 'restoring';
+    await writeJournal(journalPath, journal);
+    for (const operation of [...journal.operations].reverse()) {
+        await restoreOne(journal, operation.path, operation.beforeHash, operation.beforeMode, operation.afterHash, operation.backupPath);
+    }
+    const manifest = journal.manifest;
+    if (manifest) {
+        await restoreOne(journal, DOCS_MANIFEST_FILE, manifest.beforeHash, manifest.beforeMode, manifest.afterHash, manifest.backupPath);
+    }
+    await removeTransaction(transactionRoot, journal);
+};
+const listStateEntries = async (stateRoot) => {
+    try {
+        return (await readdir(stateRoot, { withFileTypes: true }))
+            .map((entry) => entry.name)
+            .sort((left, right) => left.localeCompare(right));
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return [];
+        throw error;
+    }
+};
+const isProcessAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (isErrno(error, 'ESRCH'))
+            return false;
+        if (isErrno(error, 'EPERM'))
+            return true;
+        throw error;
+    }
+};
+const assertJournalOwnerInactive = (journal) => {
+    if (journal.ownerPid !== null && isProcessAlive(journal.ownerPid)) {
+        throw new DocsTransactionError('FG-DOC-CONCURRENT', `Documentation transaction is still owned by process ${journal.ownerPid}`);
+    }
+};
+const realStateDirectoryExists = async (directoryPath) => {
+    const info = await lstat(directoryPath).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (!info)
+        return false;
+    if (!info.isDirectory() || info.isSymbolicLink()) {
+        throw recoveryError(`Unsafe documentation transaction residue: ${directoryPath}`);
+    }
+    return true;
+};
+const realStateFileExists = async (filePath) => {
+    const info = await lstat(filePath).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (!info)
+        return false;
+    if (!info.isFile() || info.isSymbolicLink()) {
+        throw recoveryError(`Unsafe documentation transaction residue: ${filePath}`);
+    }
+    return true;
+};
+const parseRecoveryClaim = (bytes, expectedTargetRoot, claimPath) => {
+    let value;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw recoveryError('Corrupt documentation recovery claim');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw recoveryError('Corrupt documentation recovery claim');
+    }
+    const raw = value;
+    if (raw.schemaVersion !== 1
+        || !Number.isSafeInteger(raw.ownerPid)
+        || raw.ownerPid <= 0
+        || typeof raw.claimId !== 'string'
+        || raw.targetRoot !== expectedTargetRoot) {
+        throw recoveryError('Corrupt or mismatched documentation recovery claim');
+    }
+    let claimId;
+    try {
+        claimId = assertTransactionId(raw.claimId);
+    }
+    catch {
+        throw recoveryError('Invalid documentation recovery claim ID');
+    }
+    return {
+        schemaVersion: 1,
+        ownerPid: raw.ownerPid,
+        claimId,
+        targetRoot: expectedTargetRoot,
+        path: claimPath,
+    };
+};
+const readRecoveryClaim = async (stateRoot, targetRoot) => {
+    const claimPath = path.join(stateRoot, RECOVERY_CLAIM_NAME);
+    const claimInfo = await lstat(claimPath).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (!claimInfo)
+        return { kind: 'missing' };
+    if (!claimInfo.isFile() || claimInfo.isSymbolicLink()) {
+        throw recoveryError('Unsafe documentation recovery claim');
+    }
+    const bytes = await readFile(claimPath).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (!bytes)
+        return { kind: 'missing' };
+    return { kind: 'ready', claim: parseRecoveryClaim(bytes, targetRoot, claimPath) };
+};
+const parseRecoveryClaimSidecar = (entry, prefix, label) => {
+    const match = new RegExp(`^${prefix}(\\d+)-(.+)$`).exec(entry);
+    if (!match)
+        throw recoveryError(`Invalid recovery claim ${label}: ${entry}`);
+    const ownerPid = Number.parseInt(match[1], 10);
+    let claimId;
+    try {
+        claimId = assertTransactionId(match[2]);
+    }
+    catch {
+        throw recoveryError(`Invalid recovery claim ${label}: ${entry}`);
+    }
+    if (!Number.isSafeInteger(ownerPid) || ownerPid <= 0) {
+        throw recoveryError(`Invalid recovery claim ${label} owner: ${entry}`);
+    }
+    return { ownerPid, claimId };
+};
+const cleanRecoveryClaimSidecars = async (stateRoot, prefix, label) => {
+    for (const entry of await listStateEntries(stateRoot)) {
+        if (!entry.startsWith(prefix))
+            continue;
+        const { ownerPid } = parseRecoveryClaimSidecar(entry, prefix, label);
+        const sidecarPath = path.join(stateRoot, entry);
+        if (!(await realStateFileExists(sidecarPath)))
+            continue;
+        if (isProcessAlive(ownerPid)) {
+            throw new DocsTransactionError('FG-DOC-CONCURRENT', `Documentation recovery claim ${label} is still owned by process ${ownerPid}`);
+        }
+        const removed = await unlink(sidecarPath).then(() => true, (error) => {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        });
+        if (removed)
+            await syncDirectory(stateRoot);
+    }
+};
+const reclaimDeadRecoveryClaim = async (stateRoot, targetRoot, claimPath) => {
+    const observationPath = path.join(stateRoot, `${RECOVERY_CLAIM_OBSERVING_PREFIX}${process.pid}-${randomUUID()}`);
+    try {
+        await link(claimPath, observationPath);
+    }
+    catch (error) {
+        if (isErrno(error, 'ENOENT'))
+            return false;
+        throw error;
+    }
+    await syncDirectory(stateRoot);
+    try {
+        if (!(await realStateFileExists(observationPath)))
+            return false;
+        const pinned = parseRecoveryClaim(await readFile(observationPath), targetRoot, observationPath);
+        if (isProcessAlive(pinned.ownerPid)) {
+            throw new DocsTransactionError('FG-DOC-CONCURRENT', `Documentation recovery is already running in process ${pinned.ownerPid}`);
+        }
+        for (let attempt = 0; attempt < 100; attempt += 1) {
+            const observationInfo = await lstat(observationPath);
+            const currentInfo = await lstat(claimPath).catch((error) => {
+                if (error.code === 'ENOENT')
+                    return null;
+                throw error;
+            });
+            if (!currentInfo)
+                return false;
+            if (!currentInfo.isFile() || currentInfo.isSymbolicLink()) {
+                throw recoveryError('Unsafe documentation recovery claim');
+            }
+            if (currentInfo.dev !== observationInfo.dev
+                || currentInfo.ino !== observationInfo.ino)
+                return false;
+            if (observationInfo.nlink < 2) {
+                throw recoveryError('Invalid documentation recovery claim link count');
+            }
+            if (observationInfo.nlink === 2) {
+                try {
+                    await unlink(claimPath);
+                }
+                catch (error) {
+                    if (isErrno(error, 'ENOENT'))
+                        return false;
+                    throw error;
+                }
+                await syncDirectory(stateRoot);
+                return true;
+            }
+            const observers = (await listStateEntries(stateRoot))
+                .filter((entry) => entry.startsWith(RECOVERY_CLAIM_OBSERVING_PREFIX));
+            if (observers[0] !== path.basename(observationPath)) {
+                throw new DocsTransactionError('FG-DOC-CONCURRENT', 'Another process is reclaiming the documentation recovery claim');
+            }
+            await new Promise((resolve) => setTimeout(resolve, 1));
+        }
+        throw recoveryError('Documentation recovery claim link count did not stabilize');
+    }
+    finally {
+        const removed = await unlink(observationPath).then(() => true, (error) => {
+            if (error.code === 'ENOENT')
+                return false;
+            throw error;
+        });
+        if (removed)
+            await syncDirectory(stateRoot);
+    }
+};
+const acquireRecoveryClaim = async (targetRoot) => {
+    const stateRoot = path.join(targetRoot, STATE_DIRECTORY);
+    const claimPath = path.join(stateRoot, RECOVERY_CLAIM_NAME);
+    await mkdir(stateRoot, { recursive: true });
+    await cleanRecoveryClaimSidecars(stateRoot, RECOVERY_CLAIM_OBSERVING_PREFIX, 'observer');
+    await cleanRecoveryClaimSidecars(stateRoot, RECOVERY_CLAIM_PREPARING_PREFIX, 'initializer');
+    const claim = {
+        schemaVersion: 1,
+        ownerPid: process.pid,
+        claimId: randomUUID(),
+        targetRoot,
+        path: claimPath,
+    };
+    const initializerPath = path.join(stateRoot, `${RECOVERY_CLAIM_PREPARING_PREFIX}${claim.ownerPid}-${claim.claimId}`);
+    try {
+        await writeSyncedFile(initializerPath, Buffer.from(`${JSON.stringify({
+            schemaVersion: claim.schemaVersion,
+            ownerPid: claim.ownerPid,
+            claimId: claim.claimId,
+            targetRoot: claim.targetRoot,
+        }, null, 2)}\n`), 0o600);
+        await syncDirectory(stateRoot);
+        while (true) {
+            try {
+                await link(initializerPath, claimPath);
+                await syncDirectory(stateRoot);
+                await unlink(initializerPath);
+                await syncDirectory(stateRoot);
+                return claim;
+            }
+            catch (error) {
+                if (!isErrno(error, 'EEXIST'))
+                    throw error;
+            }
+            const existing = await readRecoveryClaim(stateRoot, targetRoot);
+            if (existing.kind === 'missing') {
+                await new Promise((resolve) => setTimeout(resolve, 1 + Math.floor(Math.random() * 8)));
+                continue;
+            }
+            if (isProcessAlive(existing.claim.ownerPid)) {
+                throw new DocsTransactionError('FG-DOC-CONCURRENT', `Documentation recovery is already running in process ${existing.claim.ownerPid}`);
+            }
+            if (!(await reclaimDeadRecoveryClaim(stateRoot, targetRoot, claimPath))) {
+                await new Promise((resolve) => setTimeout(resolve, 1 + Math.floor(Math.random() * 8)));
+            }
+        }
+    }
+    catch (error) {
+        await rm(initializerPath, { force: true });
+        await syncDirectory(stateRoot);
+        throw error;
+    }
+};
+const releaseRecoveryClaim = async (claim) => {
+    const stateRoot = path.dirname(claim.path);
+    const current = await readRecoveryClaim(stateRoot, claim.targetRoot);
+    if (current.kind !== 'ready'
+        || current.claim.ownerPid !== claim.ownerPid
+        || current.claim.claimId !== claim.claimId) {
+        throw recoveryError('Documentation recovery claim changed unexpectedly');
+    }
+    await unlink(claim.path).catch((error) => {
+        if (error.code === 'ENOENT') {
+            throw recoveryError('Documentation recovery claim disappeared unexpectedly');
+        }
+        throw error;
+    });
+    await syncDirectory(stateRoot);
+};
+const inspectResidue = async (stateRoot, entry, injector) => {
+    await fault(injector, { operation: 'residue', timing: 'before', path: entry });
+    const residuePath = path.join(stateRoot, entry);
+    return await realStateDirectoryExists(residuePath) ? residuePath : null;
+};
+const cleanGarbageDirectories = async (stateRoot, injector) => {
+    for (const entry of await listStateEntries(stateRoot)) {
+        if (!entry.startsWith(GARBAGE_DIRECTORY_PREFIX))
+            continue;
+        const garbagePath = await inspectResidue(stateRoot, entry, injector);
+        if (!garbagePath)
+            continue;
+        await fault(injector, { operation: 'residue', timing: 'after', path: entry });
+        await rm(garbagePath, { recursive: true, force: true });
+        await syncDirectory(stateRoot);
+    }
+};
+const cleanOrphanedPreparingDirectories = async (stateRoot, injector) => {
+    for (const entry of await listStateEntries(stateRoot)) {
+        if (!entry.startsWith(PREPARING_DIRECTORY_PREFIX))
+            continue;
+        const match = new RegExp(`^${PREPARING_DIRECTORY_PREFIX}(\\d+)-(.+)$`).exec(entry);
+        if (!match)
+            throw recoveryError(`Invalid preparing transaction directory: ${entry}`);
+        const pid = Number.parseInt(match[1], 10);
+        try {
+            assertTransactionId(match[2]);
+        }
+        catch {
+            throw recoveryError(`Invalid preparing transaction directory: ${entry}`);
+        }
+        if (!Number.isSafeInteger(pid) || pid <= 0) {
+            throw recoveryError(`Invalid preparing transaction owner: ${entry}`);
+        }
+        const preparingPath = await inspectResidue(stateRoot, entry, injector);
+        if (!preparingPath)
+            continue;
+        if (isProcessAlive(pid)) {
+            if (!(await realStateDirectoryExists(preparingPath)))
+                continue;
+            throw new DocsTransactionError('FG-DOC-CONCURRENT', `Documentation transaction is still being prepared by process ${pid}`);
+        }
+        await fault(injector, { operation: 'residue', timing: 'after', path: entry });
+        await moveStateDirectoryToGarbage(stateRoot, preparingPath);
+    }
+};
+const terminalJournalDisposition = async (journal) => {
+    const restored = journal.phase === 'restoring';
+    for (const operation of journal.operations) {
+        const current = await readManagedTarget(journal.targetRoot, operation.path);
+        const matches = restored
+            ? beforeMatches(current, operation)
+            : afterMatches(current, operation);
+        if (!matches) {
+            throw recoveryError(`Transaction tombstone is not terminal: ${operation.path}`);
+        }
+    }
+    const manifest = journal.manifest;
+    if (manifest) {
+        const current = await readManifestTarget(journal.targetRoot);
+        const matches = restored
+            ? current?.sha256 === manifest.beforeHash || (!current && manifest.beforeHash === null)
+            : current?.sha256 === manifest.afterHash;
+        if (!matches)
+            throw recoveryError('Transaction tombstone manifest is not terminal');
+    }
+    return restored ? 'restored' : 'completed';
+};
+const cleanTransactionTombstones = async (targetRoot, stateRoot, injector) => {
+    const tombstones = [];
+    for (const entry of await listStateEntries(stateRoot)) {
+        if (!entry.startsWith(TOMBSTONE_DIRECTORY_PREFIX))
+            continue;
+        const transactionId = entry.slice(TOMBSTONE_DIRECTORY_PREFIX.length);
+        try {
+            assertTransactionId(transactionId);
+        }
+        catch {
+            throw recoveryError(`Invalid transaction tombstone: ${entry}`);
+        }
+        const tombstonePath = await inspectResidue(stateRoot, entry, injector);
+        if (!tombstonePath)
+            continue;
+        const journalPath = path.join(tombstonePath, JOURNAL_FILE);
+        const journalInfo = await lstat(journalPath).catch((error) => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (!journalInfo?.isFile() || journalInfo.isSymbolicLink()) {
+            if (!journalInfo && !(await realStateDirectoryExists(tombstonePath)))
+                continue;
+            throw recoveryError(`Transaction tombstone journal is missing or unsafe: ${entry}`);
+        }
+        const journalBytes = await readFile(journalPath).catch(async (error) => {
+            if (error.code === 'ENOENT' && !(await realStateDirectoryExists(tombstonePath)))
+                return null;
+            throw error;
+        });
+        if (!journalBytes)
+            continue;
+        const journal = parseJournal(journalBytes, targetRoot);
+        assertJournalOwnerInactive(journal);
+        if (journal.transactionId !== transactionId) {
+            throw recoveryError(`Transaction tombstone ID mismatch: ${entry}`);
+        }
+        tombstones.push({
+            disposition: await terminalJournalDisposition(journal),
+            entry,
+            path: tombstonePath,
+        });
+    }
+    const disposition = tombstones[0]?.disposition ?? null;
+    if (disposition && tombstones.some((tombstone) => tombstone.disposition !== disposition)) {
+        throw recoveryError('Conflicting terminal documentation transaction tombstones');
+    }
+    for (const tombstone of tombstones) {
+        await fault(injector, { operation: 'residue', timing: 'after', path: tombstone.entry });
+        await moveStateDirectoryToGarbage(stateRoot, tombstone.path);
+    }
+    return disposition;
+};
+const recoverTransactionResidues = async (targetRoot, injector) => {
+    const stateRoot = path.join(targetRoot, STATE_DIRECTORY);
+    let disposition = null;
+    while (true) {
+        await cleanGarbageDirectories(stateRoot, injector);
+        const currentDisposition = await cleanTransactionTombstones(targetRoot, stateRoot, injector);
+        if (disposition && currentDisposition && disposition !== currentDisposition) {
+            throw recoveryError('Conflicting terminal documentation transaction tombstones');
+        }
+        disposition ??= currentDisposition;
+        await cleanOrphanedPreparingDirectories(stateRoot, injector);
+        const hasResidue = (await listStateEntries(stateRoot)).some((entry) => entry.startsWith(PREPARING_DIRECTORY_PREFIX)
+            || entry.startsWith(TOMBSTONE_DIRECTORY_PREFIX)
+            || entry.startsWith(GARBAGE_DIRECTORY_PREFIX));
+        if (!hasResidue)
+            return disposition;
+    }
+};
+export const recoverTemplateDocs = async (targetDir, options = {}) => {
+    const targetRoot = path.resolve(targetDir);
+    const { transactionRoot, journalPath } = transactionPaths(targetRoot);
+    try {
+        await assertStateDirectoriesSafe(targetRoot);
+    }
+    catch (error) {
+        if (error instanceof DocsTransactionError)
+            throw error;
+        throw recoveryError(`Cannot inspect documentation transaction state: ${error.message}`);
+    }
+    let claim;
+    try {
+        claim = await acquireRecoveryClaim(targetRoot);
+    }
+    catch (error) {
+        if (error instanceof DocsTransactionError)
+            throw error;
+        throw recoveryError(`Cannot claim documentation recovery: ${error.message}`);
+    }
+    try {
+        let residueDisposition;
+        try {
+            residueDisposition = await recoverTransactionResidues(targetRoot, options.faultInjector);
+        }
+        catch (error) {
+            if (error instanceof DocsTransactionError)
+                throw error;
+            throw recoveryError(`Cannot clean documentation transaction residue: ${error.message}`);
+        }
+        let transactionInfo;
+        try {
+            transactionInfo = await lstat(transactionRoot);
+        }
+        catch (error) {
+            if (isErrno(error, 'ENOENT'))
+                return residueDisposition ?? 'none';
+            throw recoveryError(`Cannot inspect documentation transaction: ${error.message}`);
+        }
+        if (!transactionInfo.isDirectory() || transactionInfo.isSymbolicLink()) {
+            throw recoveryError('Documentation transaction path is unsafe');
+        }
+        try {
+            const journalBytes = await readFile(journalPath);
+            const journal = parseJournal(journalBytes, targetRoot);
+            assertJournalOwnerInactive(journal);
+            await assertJournalArtifactPathsSafe(transactionRoot, journal);
+            if (await canRecoverForward(transactionRoot, journal)) {
+                await continueForward(transactionRoot, journalPath, journal);
+                return 'completed';
+            }
+            if (await canRestore(journal)) {
+                await restorePriorGeneration(transactionRoot, journalPath, journal);
+                return 'restored';
+            }
+            throw recoveryError('Documentation transaction cannot be safely completed or restored');
+        }
+        catch (error) {
+            if (error instanceof DocsTransactionError
+                && (error.code === 'FG-DOC-RECOVERY' || error.code === 'FG-DOC-CONCURRENT'))
+                throw error;
+            throw recoveryError(`Documentation recovery failed: ${error.message}`);
+        }
+    }
+    finally {
+        await releaseRecoveryClaim(claim);
+    }
+};
+export const resolveTemplateDocsConflict = async (bundle, targetDir, relativePath, options = {}) => {
+    let managedPath;
+    try {
+        managedPath = assertManagedPath(relativePath);
+    }
+    catch (error) {
+        throw error instanceof DocsTransactionError ? error : docsError('Invalid conflict path');
+    }
+    if (!bundle.files.has(managedPath)) {
+        throw docsError(`Conflict path is not managed by the bundled documentation: ${managedPath}`);
+    }
+    const targetRoot = path.resolve(targetDir);
+    await assertNoOpenTransaction(targetRoot);
+    const inspection = await inspectTemplateDocs(bundle, targetRoot);
+    const status = planTemplateDocsUpdate(inspection);
+    const selected = status.files.find((file) => file.path === managedPath);
+    if (!selected || selected.action !== 'conflict') {
+        throw new DocsTransactionError('FG-DOC-002', `Path is not a documentation conflict: ${managedPath}`);
+    }
+    const prepared = await prepareTransaction(bundle, targetRoot, status, options, selected);
+    await executeOwnedTransaction(prepared, options.faultInjector);
+};