@astrosheep/keiyaku 2.8.4 → 2.9.0

package/build/core/task-contract.js

@@ -0,0 +1,224 @@
+import { FlowError } from "../flow-error.js";
+import { withLockHeldTaskBoard } from "./task-git-store.js";
+import { prepareTaskDocumentReplacements, taskRepositoryFromLockedBoard } from "./task-store-repository.js";
+import { containsCommit, createLandingCommit, createTaskBoardCommit, inspectCurrentBranch, publishForwardTaskBoardCommit, readableRefHead, reconcileTaskIndex, refHead, sameTaskSourceBytes, taskContractAtCommit, taskWritesFromSources, updateBranch, updateTargetRef, } from "./task/settlement-git.js";
+import { contractPointerDocument, doneTaskReplacement, reopenedTaskDocument, requireHealthySettlementBoard, requireSettledTask, selectReadyTaskForBind, taskForContract, } from "./task/settlement-policy.js";
+import { stableRepoRoot } from "./worktree-path.js";
+async function clearAttemptedPointer(input) {
+    const current = requireSettledTask(await input.repository.read(), input.task.id);
+    if (current.contractId === input.contractId) {
+        await replaceTaskDocument(input.repository, contractPointerDocument(current, undefined));
+    }
+}
+async function replaceTaskDocument(repository, replacement) {
+    return repository.mutate(() => ({
+        replacements: [replacement],
+        select: (resulting) => requireSettledTask(resulting, replacement.id),
+    }));
+}
+export async function settleTaskBoardForBind(input, deps = {}) {
+    return withLockHeldTaskBoard(input.cwd, async (transaction) => {
+        if (transaction.location.mode !== "git") {
+            throw new FlowError("NOT_GIT_REPO", "task bind requires Git task storage");
+        }
+        const hubCwd = transaction.location.root;
+        const repository = taskRepositoryFromLockedBoard(transaction);
+        const branch = inspectCurrentBranch(hubCwd);
+        const board = requireHealthySettlementBoard(await repository.read());
+        const selected = input.taskId === undefined
+            ? undefined
+            : selectReadyTaskForBind(board, input.taskId);
+        if (selected) {
+            await replaceTaskDocument(repository, contractPointerDocument(selected, input.contractId));
+        }
+        const firstCommit = createTaskBoardCommit({
+            cwd: hubCwd,
+            gitDir: transaction.location.gitDir,
+            root: transaction.location.root,
+            parent: branch.head,
+            sources: transaction.sources,
+            subject: selected
+                ? `Bind task ${selected.id} to contract ${input.contractId}`
+                : `Flush task board for contract ${input.contractId}`,
+        });
+        try {
+            await updateBranch({ cwd: hubCwd, ref: branch.ref, next: firstCommit, expected: branch.head }, deps);
+        }
+        catch (error) {
+            if (selected) {
+                await clearAttemptedPointer({ repository, task: selected, contractId: input.contractId });
+                const concurrentHead = refHead(hubCwd, branch.ref);
+                if (taskContractAtCommit(hubCwd, concurrentHead, selected.id) === input.contractId) {
+                    await publishForwardTaskBoardCommit({
+                        cwd: hubCwd,
+                        ref: branch.ref,
+                        gitDir: transaction.location.gitDir,
+                        root: transaction.location.root,
+                        sources: transaction.sources,
+                        subject: `Clear failed contract ${input.contractId} from task ${selected.id}`,
+                    }, deps);
+                }
+            }
+            throw error;
+        }
+        try {
+            reconcileTaskIndex(hubCwd, firstCommit);
+        }
+        catch (indexError) {
+            if (selected) {
+                await clearAttemptedPointer({ repository, task: selected, contractId: input.contractId });
+                await publishForwardTaskBoardCommit({
+                    cwd: hubCwd,
+                    ref: branch.ref,
+                    gitDir: transaction.location.gitDir,
+                    root: transaction.location.root,
+                    sources: transaction.sources,
+                    subject: `Clear failed contract ${input.contractId} from task ${selected.id}`,
+                }, deps);
+            }
+            throw indexError;
+        }
+        try {
+            const ledger = await input.publishLedger(firstCommit);
+            return {
+                boardCommit: firstCommit,
+                ledger,
+                ...(selected ? { task: requireSettledTask(await repository.read(), selected.id) } : {}),
+            };
+        }
+        catch (publishError) {
+            if (!selected)
+                throw publishError;
+            await clearAttemptedPointer({ repository, task: selected, contractId: input.contractId });
+            await publishForwardTaskBoardCommit({
+                cwd: hubCwd,
+                ref: branch.ref,
+                gitDir: transaction.location.gitDir,
+                root: transaction.location.root,
+                sources: transaction.sources,
+                subject: `Clear failed contract ${input.contractId} from task ${selected.id}`,
+            }, deps);
+            throw publishError;
+        }
+    });
+}
+export async function reconcileTaskForfeit(input) {
+    const hubRoot = await stableRepoRoot(input.cwd);
+    return withLockHeldTaskBoard(hubRoot, async (transaction) => {
+        if (transaction.location.mode !== "git") {
+            throw new FlowError("NOT_GIT_REPO", "task forfeit requires Git task storage");
+        }
+        const repository = taskRepositoryFromLockedBoard(transaction);
+        const matched = taskForContract(await repository.read(), input.contractId);
+        const ledger = await input.publishLedger();
+        if (!matched)
+            return { ledger };
+        const task = await replaceTaskDocument(repository, reopenedTaskDocument(matched));
+        return {
+            ledger,
+            task,
+        };
+    });
+}
+/**
+ * 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) {
+    const hubRoot = await stableRepoRoot(input.cwd);
+    let lastTargetHead = input.targetHead;
+    let lastPublishError;
+    let acceptedMovement;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        const result = await withLockHeldTaskBoard(hubRoot, async (transaction) => {
+            if (transaction.location.mode !== "git") {
+                throw new FlowError("NOT_GIT_REPO", "task landing requires Git task storage");
+            }
+            // Each attempt reads fresh target and board facts while holding the
+            // common task lock. A losing CAS exits before the next attempt.
+            const targetHead = refHead(input.cwd, input.targetRef);
+            lastTargetHead = targetHead;
+            const repository = taskRepositoryFromLockedBoard(transaction);
+            const board = requireHealthySettlementBoard(await repository.read());
+            const replacement = doneTaskReplacement(board, input.contractId);
+            const prepared = replacement
+                ? prepareTaskDocumentReplacements(transaction.sources, [replacement])
+                : { sources: transaction.sources, board };
+            const finalSources = prepared.sources;
+            requireHealthySettlementBoard(prepared.board);
+            let mergeCommit = targetHead;
+            let movement = acceptedMovement?.mergeCommit === targetHead ? acceptedMovement : undefined;
+            if (!containsCommit(input.cwd, input.deliveryHead, targetHead)) {
+                mergeCommit = createLandingCommit({
+                    cwd: input.cwd,
+                    gitDir: transaction.location.gitDir,
+                    root: transaction.location.root,
+                    base: input.baseCommit,
+                    target: targetHead,
+                    delivery: input.deliveryHead,
+                    sources: finalSources,
+                    contractId: input.contractId,
+                    targetBranch: input.targetBranch,
+                });
+                await input.beforeCas?.(mergeCommit, targetHead);
+                try {
+                    updateTargetRef(input.cwd, input.targetRef, mergeCommit, targetHead);
+                    movement = { mergeCommit, oldHead: targetHead };
+                    acceptedMovement = movement;
+                }
+                catch {
+                    const current = readableRefHead(input.cwd, input.targetRef);
+                    if (!current || !containsCommit(input.cwd, input.deliveryHead, current)) {
+                        return { kind: "retry" };
+                    }
+                    mergeCommit = current;
+                    movement = acceptedMovement?.mergeCommit === mergeCommit ? acceptedMovement : undefined;
+                }
+            }
+            const warnings = [];
+            if (!sameTaskSourceBytes(transaction.location.root, transaction.sources, finalSources)) {
+                await transaction.replace(taskWritesFromSources(finalSources));
+            }
+            try {
+                reconcileTaskIndex(transaction.location.root, mergeCommit);
+            }
+            catch (error) {
+                warnings.push(`Accepted landing ${mergeCommit}, but task index reconciliation failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            try {
+                await input.publishLedger?.(mergeCommit);
+            }
+            catch (error) {
+                lastPublishError = error;
+                return { kind: "retry" };
+            }
+            const reconcileWarnings = movement
+                ? await input.afterCas?.(mergeCommit, movement.oldHead)
+                : undefined;
+            warnings.push(...(reconcileWarnings ?? []));
+            return {
+                kind: movement ? "accepted" : "idempotent",
+                mergeCommit,
+                ...(movement ? { oldHead: movement.oldHead } : {}),
+                ...(warnings.length > 0 ? { warnings } : {}),
+            };
+        });
+        if (result.kind === "retry")
+            continue;
+        if (result.kind === "idempotent") {
+            return {
+                mergeCommit: result.mergeCommit,
+                ...(result.warnings ? { warnings: result.warnings } : {}),
+            };
+        }
+        return {
+            mergeCommit: result.mergeCommit,
+            oldHead: result.oldHead,
+            ...(result.warnings ? { warnings: result.warnings } : {}),
+        };
+    }
+    if (lastPublishError !== undefined)
+        throw lastPublishError;
+    throw new FlowError("CONCURRENT_MODIFICATION", `target branch kept moving while claiming ${input.contractId}; last observed ${lastTargetHead}`);
+}

package/build/core/task-doctor.js

@@ -0,0 +1,14 @@
+import { rollbackOrphanTaskPointers } from "./task.js";
+import { buildTaskSourceBoard } from "./task/source-board.js";
+export async function inspectTaskDoctor(store, repository, facts) {
+    const orphans = facts.lockHeld ? [] : await rollbackOrphanTaskPointers(repository, facts.contractIds);
+    const sources = await store.read();
+    const board = buildTaskSourceBoard(sources);
+    return {
+        board,
+        sources,
+        orphans,
+        landingDiagnostics: facts.landingDiagnostics ?? [],
+        lockHeld: facts.lockHeld === true,
+    };
+}

package/build/core/task-git-actor.js

@@ -0,0 +1,38 @@
+import { spawnSync } from "node:child_process";
+const ANONYMOUS_TASK_CREATOR = "(anonymous)";
+const TASK_ACTOR_ENV = "KEIYAKU_ACTOR";
+const GIT_ACTOR_KEYS = ["keiyaku.actor", "user.name"];
+function defaultRunGit(cwd, args, env) {
+    return spawnSync("git", [...args], {
+        cwd,
+        encoding: "utf8",
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+}
+function attribution(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+export function resolveTaskCreator(cwd, deps = {}) {
+    const sourceEnv = deps.env ?? process.env;
+    const environmentActor = attribution(sourceEnv[TASK_ACTOR_ENV]);
+    if (environmentActor)
+        return environmentActor;
+    const gitEnv = { ...sourceEnv, GIT_TERMINAL_PROMPT: "0", LC_ALL: "C" };
+    const runGit = deps.runGit ?? defaultRunGit;
+    for (const key of GIT_ACTOR_KEYS) {
+        try {
+            const result = runGit(cwd, ["config", "--get", key], gitEnv);
+            if (!result.error && result.status === 0) {
+                const configuredActor = attribution(result.stdout);
+                if (configuredActor)
+                    return configuredActor;
+            }
+        }
+        catch {
+            // Creator attribution is advisory and must not prevent task creation.
+        }
+    }
+    return ANONYMOUS_TASK_CREATOR;
+}

package/build/core/task-git-runtime.js

@@ -0,0 +1,34 @@
+import { isGitRepo } from "../git/branches.js";
+import { listContractIds } from "./ledger.js";
+import { contractBoundByEngineWorktree, stableRepoRoot } from "./worktree-path.js";
+import { inspectTaskLock, openTaskStore } from "./task-git-store.js";
+import { taskRepositoryFromStore } from "./task-store-repository.js";
+import { withTaskWorktreePolicy } from "./task-worktree.js";
+import { inspectTaskDoctor } from "./task-doctor.js";
+export async function taskCommandContractId(cwd) {
+    if (!(await isGitRepo(cwd)))
+        return undefined;
+    return contractBoundByEngineWorktree(cwd);
+}
+export async function openTaskCommandRepository(cwd) {
+    const store = await openTaskStore(cwd);
+    const repository = taskRepositoryFromStore(store);
+    if (store.mode !== "git")
+        return repository;
+    const contractId = await contractBoundByEngineWorktree(cwd);
+    return contractId ? withTaskWorktreePolicy(repository, contractId) : repository;
+}
+export async function taskContractIds(cwd) {
+    return new Set(await listContractIds(await stableRepoRoot(cwd)));
+}
+export async function readTaskDoctor(cwd) {
+    const store = await openTaskStore(cwd);
+    const repository = taskRepositoryFromStore(store);
+    const gitMode = store.mode === "git";
+    const lockHeld = (await inspectTaskLock(cwd)).state === "held";
+    return inspectTaskDoctor(store, repository, {
+        contractIds: gitMode ? await taskContractIds(cwd) : new Set(),
+        landingDiagnostics: [],
+        lockHeld,
+    });
+}

package/build/core/task-git-store.js

@@ -0,0 +1,375 @@
+import { randomBytes } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { FlowError } from "../flow-error.js";
+const TASK_ID = /^k-[0-9a-f]{12}$/;
+const SQLITE_BUSY = 5;
+const LOCK_FILE = "task-lock.sqlite";
+const GIT_LOCK_FILE = "keiyaku-task-lock.sqlite";
+export class TaskLockHeldError extends Error {
+    path;
+    code = "TASK_LOCK_HELD";
+    constructor(path, options) {
+        super(`task lock is already held: ${path}`, options);
+        this.path = path;
+        this.name = "TaskLockHeldError";
+    }
+}
+function errorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isSqliteBusy(error) {
+    return typeof error === "object"
+        && error !== null
+        && "errcode" in error
+        && error.errcode === SQLITE_BUSY;
+}
+function defaultRunGit(cwd, args, input) {
+    return spawnSync("git", [...args], {
+        cwd,
+        input,
+        encoding: "utf8",
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0", LC_ALL: "C" },
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+}
+function runGit(cwd, args, input) {
+    const result = defaultRunGit(cwd, args, input);
+    if (result.error) {
+        throw new FlowError("INTERNAL_STATE", `git ${args[0]} failed: ${result.error.message}`, { cause: result.error });
+    }
+    if (result.status !== 0) {
+        const detail = result.stderr.trim() || `exit ${String(result.status)}`;
+        throw new FlowError("INTERNAL_STATE", `git ${args[0]} failed: ${detail}`);
+    }
+    return result.stdout;
+}
+function nearestDirectoryBoard(cwd) {
+    const original = path.resolve(cwd);
+    let candidate = original;
+    while (true) {
+        if (lstatIfPresent(path.join(candidate, ".keiyaku")))
+            return candidate;
+        const parent = path.dirname(candidate);
+        if (parent === candidate)
+            return original;
+        candidate = parent;
+    }
+}
+export async function locateTaskBoard(cwd) {
+    const probe = defaultRunGit(cwd, ["rev-parse", "--is-inside-work-tree", "--is-bare-repository"]);
+    if (probe.error) {
+        throw new FlowError("INTERNAL_STATE", `cannot inspect task repository: ${probe.error.message}`, { cause: probe.error });
+    }
+    if (probe.status !== 0) {
+        return { mode: "directory", root: nearestDirectoryBoard(cwd) };
+    }
+    const [insideWorktree, bare] = probe.stdout.trim().split(/\r?\n/);
+    if (bare === "true" || insideWorktree !== "true") {
+        throw new FlowError("NOT_GIT_REPO", "bare repositories are not supported for task storage");
+    }
+    const facts = runGit(cwd, ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-common-dir"], undefined);
+    const [checkoutRoot, gitDir] = facts.trimEnd().split(/\r?\n/);
+    if (!checkoutRoot || !gitDir || !path.isAbsolute(checkoutRoot) || !path.isAbsolute(gitDir)) {
+        throw new FlowError("INTERNAL_STATE", "git returned incomplete task-board location facts");
+    }
+    return {
+        mode: "git",
+        root: path.dirname(gitDir),
+        gitDir,
+    };
+}
+function taskDirectory(board) {
+    return path.join(board.root, ".keiyaku", "tasks");
+}
+function assertKeiyakuDirectory(board) {
+    const keiyakuDirectory = path.join(board.root, ".keiyaku");
+    const stat = lstatIfPresent(keiyakuDirectory);
+    if (stat && (stat.isSymbolicLink() || !stat.isDirectory())) {
+        throw new FlowError("INTERNAL_STATE", `.keiyaku is not a regular directory: ${keiyakuDirectory}`);
+    }
+}
+function taskLockPath(board) {
+    return board.mode === "git"
+        ? path.join(board.gitDir, GIT_LOCK_FILE)
+        : path.join(board.root, ".keiyaku", LOCK_FILE);
+}
+function closeQuietly(database) {
+    try {
+        database.close();
+    }
+    catch {
+        // The original operation remains authoritative.
+    }
+}
+function acquireTaskLock(lockPath) {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    let database;
+    try {
+        database = new DatabaseSync(lockPath);
+    }
+    catch (error) {
+        throw new FlowError("INTERNAL_STATE", `cannot open task lock: ${errorText(error)}`, { cause: error });
+    }
+    try {
+        database.exec("PRAGMA busy_timeout=0");
+        database.exec("PRAGMA journal_mode=DELETE");
+        database.exec("CREATE TABLE IF NOT EXISTS lock_anchor (id INTEGER PRIMARY KEY CHECK (id = 1))");
+        database.exec("BEGIN EXCLUSIVE");
+        database.prepare("SELECT id FROM lock_anchor LIMIT 1").get();
+        return database;
+    }
+    catch (error) {
+        closeQuietly(database);
+        if (isSqliteBusy(error))
+            throw new TaskLockHeldError(lockPath, { cause: error });
+        throw new FlowError("INTERNAL_STATE", `cannot acquire task lock: ${errorText(error)}`, { cause: error });
+    }
+}
+export async function inspectTaskLock(cwd) {
+    const lockPath = taskLockPath(await locateTaskBoard(cwd));
+    if (!fs.existsSync(lockPath))
+        return { state: "free", path: lockPath };
+    let database;
+    try {
+        database = new DatabaseSync(lockPath, { readOnly: true });
+    }
+    catch (error) {
+        throw new FlowError("INTERNAL_STATE", `cannot inspect task lock: ${errorText(error)}`, { cause: error });
+    }
+    try {
+        database.exec("PRAGMA busy_timeout=0");
+        database.exec("BEGIN DEFERRED");
+        database.prepare("SELECT id FROM lock_anchor LIMIT 1").get();
+        database.exec("ROLLBACK");
+        return { state: "free", path: lockPath };
+    }
+    catch (error) {
+        if (isSqliteBusy(error))
+            return { state: "held", path: lockPath };
+        throw new FlowError("INTERNAL_STATE", `cannot inspect task lock: ${errorText(error)}`, { cause: error });
+    }
+    finally {
+        closeQuietly(database);
+    }
+}
+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);
+        fsyncDirectory(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 fsyncDirectory(directory) {
+    const descriptor = fs.openSync(directory, fs.constants.O_RDONLY);
+    try {
+        fs.fsyncSync(descriptor);
+    }
+    finally {
+        fs.closeSync(descriptor);
+    }
+}
+function lstatIfPresent(target) {
+    try {
+        return fs.lstatSync(target);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+async function readTaskSources(directory) {
+    const directoryStat = lstatIfPresent(directory);
+    if (!directoryStat)
+        return [];
+    if (directoryStat.isSymbolicLink() || !directoryStat.isDirectory()) {
+        throw new FlowError("INTERNAL_STATE", `task directory is not a regular directory: ${directory}`);
+    }
+    const names = fs.readdirSync(directory)
+        .filter((name) => name.endsWith(".md"))
+        .sort((left, right) => Buffer.from(left).compare(Buffer.from(right)));
+    return names.map((name) => {
+        const sourcePath = path.join(directory, name);
+        const sourceStat = fs.lstatSync(sourcePath);
+        if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
+            throw new FlowError("INTERNAL_STATE", `task source is not a regular file: ${sourcePath}`);
+        }
+        return {
+            path: sourcePath,
+            text: fs.readFileSync(sourcePath, "utf8"),
+        };
+    });
+}
+function validatePlan(plan) {
+    validateWrites(plan.writes);
+}
+function validateWrites(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 (!TASK_ID.test(write.id)) {
+            throw new FlowError("INTERNAL_STATE", `invalid task mutation id: ${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") };
+    });
+}
+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;
+    });
+}
+function removeTaskFile(filePath) {
+    try {
+        fs.unlinkSync(filePath);
+        fsyncDirectory(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 releaseTaskLock(database, deps) {
+    try {
+        if (deps.releaseLock)
+            deps.releaseLock();
+        else
+            database.exec("COMMIT");
+    }
+    catch {
+        try {
+            database.exec("ROLLBACK");
+        }
+        catch { /* close releases the advisory lock */ }
+    }
+    finally {
+        closeQuietly(database);
+    }
+}
+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 async function openTaskStore(cwd, deps = {}) {
+    const board = await locateTaskBoard(cwd);
+    const directory = taskDirectory(board);
+    return {
+        mode: board.mode,
+        read: async () => {
+            assertKeiyakuDirectory(board);
+            return readTaskSources(directory);
+        },
+        async mutate(apply) {
+            return withLockHeldTaskBoard(cwd, async (transaction) => {
+                const plan = await apply(transaction.sources);
+                validatePlan(plan);
+                await transaction.replace(plan.writes);
+                return plan.value;
+            }, deps, board);
+        },
+    };
+}
+export async function withLockHeldTaskBoard(cwd, apply, deps = {}, locatedBoard) {
+    const board = locatedBoard ?? await locateTaskBoard(cwd);
+    const directory = taskDirectory(board);
+    assertKeiyakuDirectory(board);
+    const database = acquireTaskLock(taskLockPath(board));
+    try {
+        let sources = await readTaskSources(directory);
+        const transaction = {
+            location: board,
+            get sources() {
+                return sources;
+            },
+            async replace(writes) {
+                validateWrites(writes);
+                assertKeiyakuDirectory(board);
+                assertTaskDirectorySafety(directory);
+                const currentSources = await readTaskSources(directory);
+                if (!sameSources(sources, currentSources)) {
+                    throw new FlowError("CONCURRENT_MODIFICATION", "task sources changed while applying the mutation");
+                }
+                assertKeiyakuDirectory(board);
+                assertTaskDirectorySafety(directory);
+                const previous = capturePreviousFiles(directory, writes);
+                let applied = 0;
+                try {
+                    for (const write of writes) {
+                        writeTaskFile(directory, write, deps);
+                        applied += 1;
+                    }
+                }
+                catch (error) {
+                    try {
+                        restoreFiles(previous.slice(0, applied + 1), deps);
+                    }
+                    catch { /* the original replacement failure remains authoritative */ }
+                    throw error;
+                }
+                sources = await readTaskSources(directory);
+            },
+        };
+        return await apply(transaction);
+    }
+    finally {
+        releaseTaskLock(database, deps);
+    }
+}

package/build/core/task-repository.js

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