@astrosheep/keiyaku 2.9.8 → 2.9.10

package/build/core/task/task-contract.js

@@ -1,10 +1,10 @@
 import { FlowError } from "../../flow-error.js";
 import { assertGitObservation, requireGitRepository } from "../../git/branches.js";
-import { withLockHeldTaskBoard } from "./task-git-store.js";
+import { assertTaskBoardGeneration, withLockHeldTaskBoard, } from "./task-git-store.js";
 import { prepareTaskDocumentReplacements, taskBoardFromSourceBoard, taskRepositoryFromLockedBoard } from "./task-store-repository.js";
-import { serializeTaskDocument } from "./document.js";
 import { buildTaskSourceBoard } from "./source-board.js";
-import { composeLandingTree, containsCommit, createLandingCommit, createTaskBoardCommit, findAcceptedLandingCommit, publishTaskMutationCommit, inspectCurrentBranch, publishForwardTaskBoardCommit, reconcileTaskPathsetIndex, refHead, taskContractAtCommit, taskSettlementOwnershipAtCommit, taskSourcesAtCommit, taskWritesFromSources, trackedTaskPaths, updateBranch, updateTargetRef, } from "./settlement-git.js";
+import { formatTaskCoordinate } from "./coordinate.js";
+import { createTaskBoardCommit, publishTaskMutationCommit, inspectCurrentBranch, publishForwardTaskBoardCommit, reconcileTaskPathsetIndex, refHead, taskContractAtCommit, taskSourcesAtCommit, taskWritesFromSources, trackedTaskPaths, updateBranch, } from "./settlement-git.js";
 import { contractPointerDocument, doneTaskReplacements, reopenedTaskDocument, requireHealthySettlementBoard, requireSettledTask, selectReadyTasksForBind, tasksForContract, } from "./settlement-policy.js";
 import { stableRepoRoot } from "../worktree-path.js";
 /**
@@ -38,7 +38,7 @@ function ownedTaskPaths(board, taskIds) {
     for (const taskId of taskIds) {
         let current = board.byId.get(taskId);
         while (current) {
-            paths.add(taskPath(current.id));
+            paths.add(taskPath(current.coordinate));
             current = current.parent === null ? undefined : board.byId.get(current.parent);
         }
     }
@@ -83,18 +83,18 @@ function repositoryForSettlement(transaction, sources) {
 async function clearAttemptedPointers(input) {
     return input.repository.mutate((board) => {
         const replacements = input.tasks.flatMap((task) => {
-            const current = requireSettledTask(board, task.id);
+            const current = requireSettledTask(board, task.coordinate);
             return current.contractId === input.contractId
                 ? [contractPointerDocument(current, undefined, input.updatedAt)]
                 : [];
         });
-        return { replacements, select: () => replacements.map((replacement) => replacement.id) };
+        return { replacements, select: () => replacements.map((replacement) => replacement.coordinate ?? replacement.id) };
     });
 }
 async function replaceTaskDocuments(repository, replacements) {
     return repository.mutate(() => ({
         replacements,
-        select: (resulting) => replacements.map((replacement) => requireSettledTask(resulting, replacement.id)),
+        select: (resulting) => replacements.map((replacement) => requireSettledTask(resulting, replacement.coordinate ?? replacement.id)),
     }));
 }
 async function restorePreAdmissionTaskMutations(input) {
@@ -149,9 +149,9 @@ export async function settleTaskBoardForBind(input, deps = {}) {
         if (taskBound && selectedTasks.length > 0) {
             await replaceTaskDocuments(repository, selectedTasks.map((task) => contractPointerDocument(task, contractId, updatedAt)));
         }
-        const taskIds = taskBound ? selectedTasks.map((t) => t.id) : undefined;
+        const taskIds = taskBound ? selectedTasks.map((t) => t.coordinate) : undefined;
         const selectedPaths = ownedTaskPaths(await repository.read(), taskIds);
-        const mutationPaths = taskBound ? selectedTasks.map((t) => taskPath(t.id)) : [];
+        const mutationPaths = taskBound ? selectedTasks.map((t) => taskPath(t.coordinate)) : [];
         const selectCurrentSettlement = async () => selectSettlementSources({
             root: transaction.location.root,
             sources: repository.sources(),
@@ -166,7 +166,7 @@ export async function settleTaskBoardForBind(input, deps = {}) {
         try {
             const taskLabel = taskBound
                 ? selectedTasks.length === 1
-                    ? `task ${selectedTasks[0].id}`
+                    ? `task ${selectedTasks[0].coordinate}`
                     : `${selectedTasks.length} tasks`
                 : "";
             firstCommit = await makeBoardCommit({
@@ -182,7 +182,7 @@ export async function settleTaskBoardForBind(input, deps = {}) {
         }
         catch (error) {
             if (taskBound) {
-                await restorePreAdmissionTaskMutations({ transaction, taskIds: selectedTasks.map((task) => task.id), previousSources });
+                await restorePreAdmissionTaskMutations({ transaction, taskIds: selectedTasks.map((task) => task.coordinate), previousSources });
             }
             throw error;
         }
@@ -192,7 +192,7 @@ export async function settleTaskBoardForBind(input, deps = {}) {
         catch (error) {
             if (taskBound) {
                 const concurrentHead = await refHead(hubCwd, branch.ref);
-                const concurrentMatches = await Promise.all(selectedTasks.map(async (task) => (await taskContractAtCommit(hubCwd, concurrentHead, task.id)) === contractId));
+                const concurrentMatches = await Promise.all(selectedTasks.map(async (task) => (await taskContractAtCommit(hubCwd, concurrentHead, task.coordinate)) === contractId));
                 if (concurrentMatches.every(Boolean)) {
                     await rollForwardClearAttemptedPointer({
                         repository, selected: selectedTasks, contractId, hubCwd,
@@ -202,7 +202,7 @@ export async function settleTaskBoardForBind(input, deps = {}) {
                     });
                 }
                 else {
-                    await restorePreAdmissionTaskMutations({ transaction, taskIds: selectedTasks.map((task) => task.id), previousSources });
+                    await restorePreAdmissionTaskMutations({ transaction, taskIds: selectedTasks.map((task) => task.coordinate), previousSources });
                 }
             }
             throw error;
@@ -228,7 +228,7 @@ export async function settleTaskBoardForBind(input, deps = {}) {
                 boardCommit: firstCommit,
                 contractId,
                 ledger,
-                ...(taskBound && selectedTasks.length > 0 ? { tasks: selectedTasks.map((t) => requireSettledTask(boardAfter, t.id)) } : {}),
+                ...(taskBound && selectedTasks.length > 0 ? { tasks: selectedTasks.map((t) => requireSettledTask(boardAfter, t.coordinate)) } : {}),
                 evidence: selection.evidence,
             };
         }
@@ -256,207 +256,116 @@ export async function reconcileTaskForfeit(input) {
             }
             throw new FlowError("NOT_GIT_REPO", "task forfeit requires Git task storage");
         }
+        assertTaskBoardGeneration(transaction, input.expectedGeneration);
         const repository = taskRepositoryFromLockedBoard(transaction);
-        const matched = tasksForContract(await repository.read(), input.contractId);
-        const ledger = await input.publishLedger();
-        if (matched.length === 0)
-            return { ledger };
+        const branch = await inspectCurrentBranch(transaction.location.root);
+        const trackedPaths = await trackedTaskPaths(transaction.location.root, branch.head);
+        const branchSources = await taskSourcesAtCommit(transaction.location.root, transaction.location.root, branch.head, trackedPaths);
+        if (!branchSources)
+            throw new FlowError("INTERNAL_STATE", `task branch ${branch.head} lost tracked task sources`);
+        const branchBoard = requireHealthySettlementBoard(taskBoardFromSourceBoard(buildTaskSourceBoard(branchSources)));
+        const matched = tasksForContract(branchBoard, input.contractId);
+        const worktreeMatched = tasksForContract(await repository.read(), input.contractId);
+        if (matched.length === 0 && worktreeMatched.length === 0) {
+            input.observeEffect?.({ effect: "task-source-reconciliation", status: "succeeded", taskCount: 0, detail: "current" });
+            input.observeEffect?.({ effect: "task-reconciliation", status: "succeeded", commit: branch.head, detail: "current" });
+            input.observeEffect?.({ effect: "task-index-reconciliation", status: "succeeded", commit: branch.head });
+            return { ledger: await input.publishLedger() };
+        }
         const reopenedDocuments = matched.map((task) => reopenedTaskDocument(task, updatedAt));
-        const reopened = await replaceTaskDocuments(repository, reopenedDocuments);
-        const taskLabel = matched.length === 1 ? `task ${matched[0].id}` : `${matched.length} tasks`;
+        const prepared = prepareTaskDocumentReplacements(branchSources, reopenedDocuments);
+        const projectionIds = matched.length > 0 ? matched.map((task) => task.coordinate) : worktreeMatched.map((task) => task.coordinate);
+        const branchSourcesByPath = new Map(branchSources.map((source) => [sourcePath(transaction.location.root, source), source]));
+        const writes = matched.length > 0
+            ? prepared.writes
+            : taskWritesFromSources(projectionIds.map((id) => {
+                const source = branchSourcesByPath.get(taskPath(id));
+                if (!source)
+                    throw new FlowError("INTERNAL_STATE", `task ${id} is missing from authoritative task branch ${branch.head}`);
+                return source;
+            }));
+        const reopened = projectionIds.map((id) => requireSettledTask(prepared.board, id));
+        const taskLabel = projectionIds.length === 1 ? `task ${projectionIds[0]}` : `${projectionIds.length} tasks`;
+        let indexSucceeded = false;
         await publishTaskMutationCommit({
             cwd: transaction.location.root,
             gitDir: transaction.location.gitDir,
-            writes: reopenedDocuments.map((document) => ({ id: document.id, text: serializeTaskDocument(document) })),
+            writes,
             subject: `Reopen ${taskLabel} after forfeit of ${input.contractId}`,
+            observeEffect: (effect) => {
+                input.observeEffect?.(effect);
+                if (effect.effect === "task-index-reconciliation" && effect.status === "succeeded")
+                    indexSucceeded = true;
+            },
         });
+        if (!indexSucceeded)
+            throw new FlowError("INTERNAL_STATE", "task index reconciliation failed before forfeit ledger publication");
+        try {
+            await transaction.replace(writes);
+            input.observeEffect?.({ effect: "task-source-reconciliation", status: "succeeded", taskCount: reopened.length, detail: "materialized" });
+        }
+        catch (error) {
+            input.observeEffect?.({ effect: "task-source-reconciliation", status: "failed", error });
+            throw error;
+        }
+        const ledger = await input.publishLedger();
         return { ledger, tasks: reopened };
     });
 }
-/**
- * Claim owns the sole task-board settlement after target CAS. Contract branch
- * task trees are fossils: the candidate is the code-only three-way merge plus
- * one complete snapshot of the common hub board held under its repository lock.
- */
-export async function settleTaskBoardForLanding(input, deps = {}) {
-    const updatedAt = new Date().toISOString();
-    await requireGitRepository(input.cwd, "task landing");
+/** Replay the claim's folded task selection after target+ledger authority commits. */
+export async function replayClaimTasks(input) {
+    await requireGitRepository(input.cwd, "task claim replay");
     const hubRoot = await stableRepoRoot(input.cwd);
-    const ownership = await taskSettlementOwnershipAtCommit(input.cwd, input.baseCommit, input.contractId);
-    const reconcileIndex = deps.reconcileTaskPathsetIndex ?? reconcileTaskPathsetIndex;
-    let lastTargetHead = input.targetHead;
-    let lastPostCasError;
-    let acceptedMovement;
-    for (let attempt = 0; attempt < 4; attempt += 1) {
-        const result = await withLockHeldTaskBoard(hubRoot, async (transaction) => {
-            if (transaction.location.mode !== "git") {
-                if (transaction.location.capability === "unavailable") {
-                    assertGitObservation({ capability: "unavailable" }, "task landing");
-                }
-                throw new FlowError("NOT_GIT_REPO", "task landing requires Git task storage");
+    return await withLockHeldTaskBoard(hubRoot, async (transaction) => {
+        if (transaction.location.mode !== "git") {
+            if (transaction.location.capability === "unavailable") {
+                assertGitObservation({ capability: "unavailable" }, "task claim replay");
             }
-            // Each attempt reads fresh target and board facts while holding the
-            // common task lock. A losing CAS exits before the next attempt.
+            throw new FlowError("NOT_GIT_REPO", "task claim replay requires Git task storage");
+        }
+        const hubBranch = await inspectCurrentBranch(transaction.location.root);
+        const materializeHub = hubBranch.ref === input.targetRef;
+        const selectedPaths = input.taskIds.map(taskPath);
+        for (let attempt = 0; attempt < 4; attempt += 1) {
             const targetHead = await refHead(input.cwd, input.targetRef);
-            lastTargetHead = targetHead;
-            const selectedPaths = ownership.paths;
-            const acceptedLanding = acceptedMovement?.mergeCommit === targetHead
-                ? targetHead
-                : await findAcceptedLandingCommit({
-                    cwd: input.cwd,
-                    gitDir: transaction.location.gitDir,
-                    root: transaction.location.root,
-                    base: input.baseCommit,
-                    target: targetHead,
-                    delivery: input.deliveryHead,
-                    contractId: input.contractId,
-                    targetBranch: input.targetBranch,
-                    ownedPaths: selectedPaths,
-                    settledPaths: ownership.taskIds.map(taskPath),
-                });
-            const deliveryAlreadyAccepted = ownership.taskIds.length === 0
-                && await containsCommit(input.cwd, input.deliveryHead, targetHead);
-            if (acceptedLanding !== undefined || deliveryAlreadyAccepted) {
-                const mergeCommit = acceptedLanding ?? targetHead;
-                const movement = acceptedMovement?.mergeCommit === targetHead ? acceptedMovement : undefined;
-                const authoritativeSources = selectedPaths.length > 0
-                    ? await taskSourcesAtCommit(input.cwd, transaction.location.root, targetHead, selectedPaths)
-                    : [];
-                if (!authoritativeSources) {
-                    throw new FlowError("INTERNAL_STATE", `accepted landing ${mergeCommit} lost an owned task path`);
+            const paths = await trackedTaskPaths(input.cwd, targetHead);
+            const sources = await taskSourcesAtCommit(input.cwd, transaction.location.root, targetHead, paths);
+            if (!sources)
+                throw new FlowError("INTERNAL_STATE", `claim target ${targetHead} lost tracked task sources`);
+            const board = requireHealthySettlementBoard(taskBoardFromSourceBoard(buildTaskSourceBoard(sources)));
+            const replacements = doneTaskReplacements(board, input.contractId, input.taskIds, input.updatedAt);
+            if (replacements.length === 0) {
+                const selected = new Set(selectedPaths);
+                const writes = taskWritesFromSources(sources.filter((source) => selected.has(sourcePath(transaction.location.root, source))));
+                if (materializeHub) {
+                    if (writes.length > 0)
+                        await transaction.replace(writes);
+                    await reconcileTaskPathsetIndex(transaction.location.root, targetHead, selectedPaths);
                 }
-                const selection = selectSettlementSources({
-                    root: transaction.location.root,
-                    sources: authoritativeSources,
-                    trackedPaths: await trackedTaskPaths(input.cwd, targetHead),
-                    ownedPaths: selectedPaths,
-                    mutationPaths: selectedPaths,
-                });
-                const currentText = new Map(transaction.sources.map((source) => [sourcePath(transaction.location.root, source), source.text]));
-                const writes = authoritativeSources.filter((source) => currentText.get(sourcePath(transaction.location.root, source)) !== source.text);
-                if (writes.length > 0)
-                    await transaction.replace(taskWritesFromSources(writes));
-                try {
-                    await reconcileIndex(transaction.location.root, targetHead, selectedPaths);
-                }
-                catch (error) {
-                    lastPostCasError = error;
-                    return { kind: "retry" };
-                }
-                try {
-                    await input.publishLedger?.(mergeCommit);
-                }
-                catch (error) {
-                    lastPostCasError = error;
-                    return { kind: "retry" };
-                }
-                const reconcileWarnings = movement
-                    ? await input.afterCas?.(mergeCommit, movement.oldHead)
-                    : undefined;
-                return {
-                    kind: movement ? "accepted" : "idempotent",
-                    mergeCommit,
-                    ...(movement ? { oldHead: movement.oldHead } : {}),
-                    ...(reconcileWarnings && reconcileWarnings.length > 0 ? { warnings: reconcileWarnings } : {}),
-                    evidence: selection.evidence,
-                };
-            }
-            // No durable receipt exists, so this remains a first-publication attempt:
-            // validate mutable hub authority before composing or publishing anything.
-            const repository = repositoryForSettlement(transaction, transaction.sources);
-            const board = requireHealthySettlementBoard(await repository.read());
-            const replacements = doneTaskReplacements(board, input.contractId, ownership.taskIds, updatedAt);
-            const prepared = replacements.length > 0
-                ? prepareTaskDocumentReplacements(transaction.sources, replacements)
-                : { sources: transaction.sources, board };
-            const finalSources = prepared.sources;
-            requireHealthySettlementBoard(prepared.board);
-            const selection = selectSettlementSources({
-                root: transaction.location.root,
-                sources: finalSources,
-                trackedPaths: await trackedTaskPaths(input.cwd, targetHead),
-                ownedPaths: selectedPaths,
-                // Bind-base ownership, unlike incidental hub bytes, authorizes a path
-                // even when a concurrent target commit removed it.
-                mutationPaths: selectedPaths,
-            });
-            const selected = new Set(selection.evidence.selectedPaths);
-            const missingOwnedPaths = selectedPaths.filter((ownedPath) => !selected.has(ownedPath));
-            if (missingOwnedPaths.length > 0) {
-                throw new FlowError("INTERNAL_STATE", `hub board lost bind-base-owned task paths: ${missingOwnedPaths.join(", ")}`);
+                return { taskCount: input.taskIds.length, commit: targetHead, worktree: materializeHub ? "materialized" : "ref-only" };
             }
-            const candidateTree = await composeLandingTree({
+            const prepared = prepareTaskDocumentReplacements(sources, replacements);
+            const commit = await createTaskBoardCommit({
                 cwd: input.cwd,
                 gitDir: transaction.location.gitDir,
                 root: transaction.location.root,
-                base: input.baseCommit,
-                target: targetHead,
-                delivery: input.deliveryHead,
-                sources: selection.sources,
+                parent: targetHead,
+                sources: prepared.sources,
+                subject: `Complete ${replacements.length === 1 ? `task ${replacements[0].coordinate ?? formatTaskCoordinate(replacements[0].namespace ?? null, replacements[0].id)}` : `${replacements.length} tasks`} after claim of ${input.contractId}`,
             });
-            const mergeCommit = await createLandingCommit({
-                cwd: input.cwd,
-                target: targetHead,
-                delivery: input.deliveryHead,
-                tree: candidateTree,
-                contractId: input.contractId,
-                targetBranch: input.targetBranch,
-            });
-            await input.beforeCas?.(mergeCommit, targetHead);
-            let movement;
-            try {
-                await updateTargetRef(input.cwd, input.targetRef, mergeCommit, targetHead);
-                movement = { mergeCommit, oldHead: targetHead };
-                acceptedMovement = movement;
-            }
-            catch {
-                return { kind: "retry" };
-            }
-            const warnings = [];
-            if (replacements.length > 0) {
-                await transaction.replace(taskWritesFromSources(selection.sources));
-            }
-            try {
-                await reconcileIndex(transaction.location.root, mergeCommit, selectedPaths);
-            }
-            catch (error) {
-                lastPostCasError = error;
-                return { kind: "retry" };
-            }
             try {
-                await input.publishLedger?.(mergeCommit);
+                await updateBranch({ cwd: input.cwd, ref: input.targetRef, next: commit, expected: targetHead }, {});
+                if (materializeHub) {
+                    await transaction.replace(prepared.writes);
+                    await reconcileTaskPathsetIndex(transaction.location.root, commit, selectedPaths);
+                }
+                return { taskCount: input.taskIds.length, commit, worktree: materializeHub ? "materialized" : "ref-only" };
             }
             catch (error) {
-                lastPostCasError = error;
-                return { kind: "retry" };
+                if (attempt === 3)
+                    throw error;
             }
-            const reconcileWarnings = await input.afterCas?.(mergeCommit, movement.oldHead);
-            warnings.push(...(reconcileWarnings ?? []));
-            return {
-                kind: "accepted",
-                mergeCommit,
-                oldHead: movement.oldHead,
-                ...(warnings.length > 0 ? { warnings } : {}),
-                evidence: selection.evidence,
-            };
-        });
-        if (result.kind === "retry")
-            continue;
-        if (result.kind === "idempotent") {
-            return {
-                mergeCommit: result.mergeCommit,
-                ...(result.warnings ? { warnings: result.warnings } : {}),
-                ...(result.evidence ? { evidence: result.evidence } : {}),
-            };
         }
-        return {
-            mergeCommit: result.mergeCommit,
-            oldHead: result.oldHead,
-            ...(result.warnings ? { warnings: result.warnings } : {}),
-            ...(result.evidence ? { evidence: result.evidence } : {}),
-        };
-    }
-    if (lastPostCasError !== undefined)
-        throw lastPostCasError;
-    throw new FlowError("CONCURRENT_MODIFICATION", `target branch kept moving while claiming ${input.contractId}; last observed ${lastTargetHead}`);
+        throw new FlowError("CONCURRENT_MODIFICATION", `claim target ${input.targetRef} kept moving during task replay`);
+    });
 }

package/build/core/task/task-file-transaction.js

@@ -0,0 +1,171 @@
+import { createHash, randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { FlowError } from "../../flow-error.js";
+import { syncDirectorySync } from "../../fs/durability.js";
+import { isTaskCoordinate } from "./coordinate.js";
+export function atomicReplaceTaskFile(filePath, text, _deps) {
+    const directory = path.dirname(filePath);
+    fs.mkdirSync(directory, { recursive: true });
+    const temporary = path.join(directory, `.${path.basename(filePath)}.${process.pid}.${randomBytes(12).toString("hex")}.tmp`);
+    let descriptor;
+    try {
+        descriptor = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o644);
+        fs.writeFileSync(descriptor, text, { encoding: "utf8" });
+        fs.fsyncSync(descriptor);
+        fs.closeSync(descriptor);
+        descriptor = undefined;
+        fs.renameSync(temporary, filePath);
+        syncDirectorySync(directory);
+    }
+    catch (error) {
+        if (descriptor !== undefined) {
+            try {
+                fs.closeSync(descriptor);
+            }
+            catch { /* preserve original failure */ }
+        }
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch { /* absent after rename or already cleaned */ }
+        throw error;
+    }
+}
+function lstatIfPresent(target) {
+    try {
+        return fs.lstatSync(target);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export function validateTaskMutationWrites(writes) {
+    if (writes.length === 0) {
+        throw new FlowError("INTERNAL_STATE", "task mutation must contain at least one write");
+    }
+    const targets = new Set();
+    for (const write of writes) {
+        const target = `${write.id}.md`;
+        if (!isTaskCoordinate(write.id)) {
+            throw new FlowError("INTERNAL_STATE", `invalid task mutation coordinate: ${write.id}`);
+        }
+        if (targets.has(target))
+            throw new FlowError("INTERNAL_STATE", `duplicate task mutation target: ${target}`);
+        targets.add(target);
+    }
+}
+function mutationTarget(write) {
+    return `${write.id}.md`;
+}
+function capturePreviousFiles(directory, writes) {
+    return writes.map((write) => {
+        const destination = path.join(directory, mutationTarget(write));
+        const stat = lstatIfPresent(destination);
+        if (!stat)
+            return { path: destination };
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            throw new FlowError("INTERNAL_STATE", `task destination is not a regular file: ${destination}`);
+        }
+        return { path: destination, text: fs.readFileSync(destination, "utf8") };
+    });
+}
+export function sameSources(left, right) {
+    return left.length === right.length && left.every((source, index) => {
+        const candidate = right[index];
+        return candidate !== undefined && source.path === candidate.path && source.text === candidate.text;
+    });
+}
+export function generationFor(location, sources) {
+    const digest = createHash("sha256").update("keiyaku-task-board-v1\0");
+    for (const source of [...sources].sort((left, right) => Buffer.from(left.path).compare(Buffer.from(right.path)))) {
+        const relativePath = path.relative(location.mode === "git" ? location.surfaceRoot : location.root, source.path).split(path.sep).join("/");
+        digest.update(String(Buffer.byteLength(relativePath))).update(":").update(relativePath);
+        digest.update(String(Buffer.byteLength(source.text))).update(":").update(source.text);
+    }
+    return { root: location.root, fingerprint: digest.digest("hex") };
+}
+export function taskBoardGeneration(transaction) {
+    return generationFor(transaction.location, transaction.sources);
+}
+export function assertTaskBoardGeneration(transaction, expected) {
+    const current = taskBoardGeneration(transaction);
+    if (current.root === expected.root && current.fingerprint === expected.fingerprint)
+        return;
+    throw new FlowError("CONCURRENT_MODIFICATION", "task board generation changed during lifecycle preparation", {
+        facts: { kind: "task_board_generation_changed", expected, current },
+    });
+}
+function removeTaskFile(filePath) {
+    try {
+        fs.unlinkSync(filePath);
+        syncDirectorySync(path.dirname(filePath));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function restoreFiles(previous, deps) {
+    for (const entry of previous) {
+        if (entry.text === undefined)
+            removeTaskFile(entry.path);
+        else
+            (deps.atomicReplace ?? atomicReplaceTaskFile)(entry.path, entry.text);
+    }
+}
+function writeTaskFile(directory, write, deps) {
+    const destination = path.join(directory, mutationTarget(write));
+    (deps.atomicReplace ?? atomicReplaceTaskFile)(destination, write.text);
+}
+function assertTaskDirectorySafety(directory) {
+    const stat = lstatIfPresent(directory);
+    if (stat && (stat.isSymbolicLink() || !stat.isDirectory())) {
+        throw new FlowError("INTERNAL_STATE", `task directory is not a regular directory: ${directory}`);
+    }
+}
+export function createTaskFileTransaction(input) {
+    return {
+        location: input.location,
+        get sources() { return input.getSources(); },
+        async replace(writes) {
+            validateTaskMutationWrites(writes);
+            input.assertBoardSafety();
+            assertTaskDirectorySafety(input.directory);
+            const currentSources = await input.readSources();
+            if (!sameSources(input.getSources(), currentSources)) {
+                throw new FlowError("CONCURRENT_MODIFICATION", "task sources changed while applying the mutation");
+            }
+            input.assertBoardSafety();
+            assertTaskDirectorySafety(input.directory);
+            const previous = capturePreviousFiles(input.directory, writes);
+            let applied = 0;
+            try {
+                for (const write of writes) {
+                    writeTaskFile(input.directory, write, input.deps);
+                    applied += 1;
+                }
+            }
+            catch (error) {
+                try {
+                    restoreFiles(previous.slice(0, applied + 1), input.deps);
+                }
+                catch { /* the original replacement failure remains authoritative */ }
+                throw error;
+            }
+            input.setSources(await input.readSources());
+        },
+        async restore(writes, previousSources) {
+            validateTaskMutationWrites(writes);
+            const currentSources = await input.readSources();
+            if (!sameSources(input.getSources(), currentSources)) {
+                throw new FlowError("CONCURRENT_MODIFICATION", "task sources changed while rolling back a failed publication");
+            }
+            const previousById = new Map(previousSources.map((source) => [path.relative(input.directory, source.path).slice(0, -3).split(path.sep).join("/"), source.text]));
+            restoreFiles(writes.map((write) => ({ path: path.join(input.directory, mutationTarget(write)), text: previousById.get(write.id) })), input.deps);
+            input.setSources(await input.readSources());
+        },
+    };
+}