@astrosheep/keiyaku 2.9.3 → 2.9.5

package/build/core/task/query.js

@@ -0,0 +1,172 @@
+import { FlowError } from "../../flow-error.js";
+import { isCommissionId } from "../ids.js";
+import { taskUpdatedAt } from "./model.js";
+import { isTaskId } from "./validation.js";
+const FILTER_FIELDS = new Set([
+    "state", "priority", "parent", "needs", "blocks", "contract", "created", "updated",
+]);
+const ORDERED_FIELDS = new Set(["priority", "created", "updated"]);
+const DISPLAY_VALUES = new Set(["ready", "blocked", "in_progress", "done", "dropped", "bound"]);
+const SORT_KEYS = new Set(["priority", "modified", "created"]);
+const RELATIVE_TIME = /^now-([1-9][0-9]*)([smhdw])$/;
+const UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+export function deriveTaskDisplay(task) {
+    if (task.state === "done")
+        return "done";
+    if (task.state === "drop")
+        return "dropped";
+    if (task.contractId !== undefined)
+        return "bound";
+    if (task.state === "in_progress")
+        return "in_progress";
+    return task.blocked ? "blocked" : "ready";
+}
+function invalidFilter(detail) {
+    throw new FlowError("INVALID_TARGET", `invalid task filter: ${detail}`);
+}
+export function parseTaskFilter(expression) {
+    const match = /^([a-z][a-z0-9_-]*)(!=|<=|>=|=|<|>)(.*)$/.exec(expression);
+    if (!match)
+        invalidFilter(`'${expression}' must use FIELD OP VALUE`);
+    const field = match[1];
+    const operator = match[2];
+    if (!FILTER_FIELDS.has(field))
+        invalidFilter(`unknown field '${field}'`);
+    if (!ORDERED_FIELDS.has(field) && operator !== "=" && operator !== "!=") {
+        invalidFilter(`field '${field}' does not support operator '${operator}'`);
+    }
+    const values = match[3].split(",");
+    if (values.some((value) => value.length === 0))
+        invalidFilter(`field '${field}' has an empty value`);
+    validateFilterValues(field, values);
+    return { field, operator, values };
+}
+function parseTimestamp(value, nowMs) {
+    const relative = RELATIVE_TIME.exec(value);
+    if (relative) {
+        const amount = Number(relative[1]);
+        const offset = amount * UNIT_MS[relative[2]];
+        if (!Number.isSafeInteger(offset))
+            invalidFilter(`timestamp '${value}' is outside the supported range`);
+        return nowMs - offset;
+    }
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp) || new Date(timestamp).toISOString() !== value) {
+        invalidFilter(`timestamp '${value}' must be canonical ISO-8601 or now-<duration>`);
+    }
+    return timestamp;
+}
+function validateFilterValues(field, values) {
+    if (field === "state") {
+        for (const value of values)
+            if (!DISPLAY_VALUES.has(value))
+                invalidFilter(`unknown state '${value}'`);
+        return;
+    }
+    if (field === "priority") {
+        for (const value of values)
+            if (!/^[0-3]$/.test(value))
+                invalidFilter(`priority '${value}' must be 0 through 3`);
+        return;
+    }
+    if (field === "created" || field === "updated") {
+        for (const value of values)
+            parseTimestamp(value, 0);
+        return;
+    }
+    if (field === "parent" || field === "needs" || field === "blocks") {
+        for (const value of values) {
+            if (field === "parent" && value === "none")
+                continue;
+            if (!isTaskId(value))
+                invalidFilter(`value '${value}' must be a canonical full task id`);
+        }
+        return;
+    }
+    if (field === "contract") {
+        for (const value of values) {
+            if (value !== "none" && !isCommissionId(value))
+                invalidFilter(`value '${value}' must be a full commission id or none`);
+        }
+    }
+}
+export function parseTaskSort(value) {
+    if (value === undefined)
+        return undefined;
+    const keys = value.split(",");
+    if (keys.some((key) => !SORT_KEYS.has(key))) {
+        const invalid = keys.find((key) => !SORT_KEYS.has(key));
+        throw new FlowError("INVALID_TARGET", `invalid task sort key '${String(invalid)}'; expected priority, modified, or created`);
+    }
+    if (new Set(keys).size !== keys.length) {
+        throw new FlowError("INVALID_TARGET", "task sort keys must not repeat");
+    }
+    return keys;
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function compareValue(left, right, operator) {
+    switch (operator) {
+        case "=": return left === right;
+        case "!=": return left !== right;
+        case "<": return left < right;
+        case "<=": return left <= right;
+        case ">": return left > right;
+        case ">=": return left >= right;
+    }
+}
+function matchesFilter(task, filter, nowMs) {
+    return filter.values.some((raw) => {
+        if (filter.field === "state")
+            return compareValue(deriveTaskDisplay(task), raw, filter.operator);
+        if (filter.field === "priority")
+            return compareValue(task.pri, Number(raw), filter.operator);
+        if (filter.field === "created")
+            return compareValue(Date.parse(task.createdAt), parseTimestamp(raw, nowMs), filter.operator);
+        if (filter.field === "updated")
+            return compareValue(Date.parse(taskUpdatedAt(task)), parseTimestamp(raw, nowMs), filter.operator);
+        const expected = raw === "none" ? null : raw;
+        if (filter.field === "parent")
+            return compareValue(task.parent ?? "\0", expected ?? "\0", filter.operator);
+        if (filter.field === "contract")
+            return compareValue(task.contractId ?? "\0", expected ?? "\0", filter.operator);
+        const relations = filter.field === "needs" ? task.needs : task.blocks;
+        return filter.operator === "=" ? relations.includes(raw) : !relations.includes(raw);
+    });
+}
+function selected(task, selection) {
+    const terminal = task.state === "done" || task.state === "drop";
+    return selection === "all" || (selection === "done" ? terminal : !terminal);
+}
+function displayOrder(task) {
+    const display = deriveTaskDisplay(task);
+    return display === "in_progress" ? 0 : display === "ready" ? 1 : display === "blocked" ? 2 : display === "bound" ? 3 : display === "done" ? 4 : 5;
+}
+function defaultCompare(left, right) {
+    return displayOrder(left) - displayOrder(right)
+        || left.pri - right.pri
+        || compareText(left.createdAt, right.createdAt)
+        || compareText(left.id, right.id);
+}
+function explicitCompare(keys, left, right) {
+    for (const key of keys) {
+        const difference = key === "priority"
+            ? left.pri - right.pri
+            : key === "modified"
+                ? compareText(taskUpdatedAt(right), taskUpdatedAt(left))
+                : compareText(right.createdAt, left.createdAt);
+        if (difference !== 0)
+            return difference;
+    }
+    return compareText(left.id, right.id);
+}
+export function selectTaskList(tasks, options = {}) {
+    const filters = (options.filters ?? []).map(parseTaskFilter);
+    const sort = parseTaskSort(options.sort);
+    const nowMs = options.nowMs ?? Date.now();
+    return tasks
+        .filter((task) => selected(task, options.selection ?? "default"))
+        .filter((task) => filters.every((filter) => matchesFilter(task, filter, nowMs)))
+        .sort(sort === undefined ? defaultCompare : (left, right) => explicitCompare(sort, left, right));
+}

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

@@ -1,19 +1,13 @@
-import { spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { FlowError } from "../../flow-error.js";
-import { parseTaskDocument } from "../task.js";
-function gitResult(cwd, args, input, env) {
-    return spawnSync("git", [...args], {
-        cwd,
-        input,
-        encoding: "utf8",
-        env: { ...process.env, ...env, GIT_TERMINAL_PROMPT: "0", LC_ALL: "C" },
-        stdio: ["pipe", "pipe", "pipe"],
-    });
+import { runGitProcess } from "../../git/core.js";
+import { parseTaskDocument } from "./task.js";
+async function gitResult(cwd, args, input, env) {
+    return await runGitProcess(cwd, args, { input, env });
 }
-function git(cwd, args, input, env) {
-    const result = gitResult(cwd, args, input, env);
+async function git(cwd, args, input, env) {
+    const result = await gitResult(cwd, args, input, env);
     if (result.error) {
         throw new FlowError("INTERNAL_STATE", `git ${args[0]} failed: ${result.error.message}`, { cause: result.error });
     }
@@ -29,36 +23,118 @@ function boardPath(root, source) {
     }
     return relative;
 }
-export function inspectCurrentBranch(cwd) {
-    const branch = gitResult(cwd, ["symbolic-ref", "--quiet", "HEAD"]);
+export async function inspectCurrentBranch(cwd) {
+    const branch = await gitResult(cwd, ["symbolic-ref", "--quiet", "HEAD"]);
     if (branch.error) {
         throw new FlowError("INTERNAL_STATE", `cannot inspect HEAD: ${branch.error.message}`, { cause: branch.error });
     }
     if (branch.status !== 0 || branch.stdout.trim() === "") {
         throw new FlowError("DETACHED_HEAD", "cannot publish task board from detached HEAD");
     }
-    return { ref: branch.stdout.trim(), head: git(cwd, ["rev-parse", "HEAD"]).trim() };
+    return { ref: branch.stdout.trim(), head: (await git(cwd, ["rev-parse", "HEAD"])).trim() };
 }
-export function createTaskBoardCommit(input) {
+export async function createTaskBoardCommit(input) {
     const temporaryDirectory = fs.mkdtempSync(path.join(input.gitDir, "keiyaku-task-index-"));
     const indexPath = path.join(temporaryDirectory, "index");
     const env = { GIT_INDEX_FILE: indexPath };
     try {
-        git(input.cwd, ["read-tree", input.parent], undefined, env);
-        git(input.cwd, ["rm", "-r", "--cached", "-f", "--ignore-unmatch", "--", ".keiyaku/tasks"], undefined, env);
+        await git(input.cwd, ["read-tree", input.parent], undefined, env);
         for (const source of input.sources) {
-            const oid = git(input.cwd, ["hash-object", "-w", "--stdin"], source.text).trim();
-            git(input.cwd, ["update-index", "--add", "--cacheinfo", `100644,${oid},${boardPath(input.root, source)}`], undefined, env);
+            const oid = (await git(input.cwd, ["hash-object", "-w", "--stdin"], source.text)).trim();
+            await git(input.cwd, ["update-index", "--add", "--cacheinfo", `100644,${oid},${boardPath(input.root, source)}`], undefined, env);
+        }
+        const tree = (await git(input.cwd, ["write-tree"], undefined, env)).trim();
+        return (await git(input.cwd, ["commit-tree", tree, "-p", input.parent, "-m", input.subject])).trim();
+    }
+    finally {
+        fs.rmSync(temporaryDirectory, { recursive: true, force: true });
+    }
+}
+function taskMutationPath(write) {
+    return `.keiyaku/tasks/${write.id}.md`;
+}
+/** Build a commit that updates only the listed task paths on top of parent. */
+export async function createTaskMutationCommit(input) {
+    if (input.writes.length === 0) {
+        throw new FlowError("INTERNAL_STATE", "task mutation commit requires at least one write");
+    }
+    const temporaryDirectory = fs.mkdtempSync(path.join(input.gitDir, "keiyaku-task-index-"));
+    const env = { GIT_INDEX_FILE: path.join(temporaryDirectory, "index") };
+    try {
+        await git(input.cwd, ["read-tree", input.parent], undefined, env);
+        for (const write of input.writes) {
+            const oid = (await git(input.cwd, ["hash-object", "-w", "--stdin"], write.text)).trim();
+            await git(input.cwd, [
+                "update-index",
+                "--add",
+                "--cacheinfo",
+                `100644,${oid},${taskMutationPath(write)}`,
+            ], undefined, env);
         }
-        const tree = git(input.cwd, ["write-tree"], undefined, env).trim();
-        return git(input.cwd, ["commit-tree", tree, "-p", input.parent, "-m", input.subject]).trim();
+        const tree = (await git(input.cwd, ["write-tree"], undefined, env)).trim();
+        const parentTree = (await git(input.cwd, ["rev-parse", `${input.parent}^{tree}`])).trim();
+        if (tree === parentTree)
+            return input.parent;
+        return (await git(input.cwd, ["commit-tree", tree, "-p", input.parent, "-m", input.subject])).trim();
     }
     finally {
         fs.rmSync(temporaryDirectory, { recursive: true, force: true });
     }
 }
-function taskTreeEntries(cwd, commit) {
-    return git(cwd, ["ls-tree", "-r", "-z", commit, "--", ".keiyaku/tasks"])
+/** Stage only the mutated task paths into the real index; leave unrelated entries alone. */
+export async function reconcileTaskMutationIndex(cwd, writes) {
+    for (const write of writes) {
+        const oid = (await git(cwd, ["hash-object", "-w", "--stdin"], write.text)).trim();
+        await git(cwd, [
+            "update-index",
+            "--add",
+            "--cacheinfo",
+            `100644,${oid},${taskMutationPath(write)}`,
+        ]);
+    }
+}
+/**
+ * Atomically publish a pathspec-scoped task micro-commit under the hub branch.
+ * Unrelated staged and unstaged non-task bytes are never read into the commit.
+ */
+export async function publishTaskMutationCommit(input, deps = {}) {
+    let lastError;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        const branch = await inspectCurrentBranch(input.cwd);
+        const commit = await createTaskMutationCommit({
+            cwd: input.cwd,
+            gitDir: input.gitDir,
+            parent: branch.head,
+            writes: input.writes,
+            subject: input.subject,
+        });
+        if (commit === branch.head) {
+            await reconcileTaskMutationIndex(input.cwd, input.writes);
+            return commit;
+        }
+        try {
+            await updateBranch({
+                cwd: input.cwd,
+                ref: branch.ref,
+                next: commit,
+                expected: branch.head,
+            }, deps);
+            try {
+                await reconcileTaskMutationIndex(input.cwd, input.writes);
+            }
+            catch {
+                // Branch fact remains authoritative; index may be repaired by a later mutation.
+            }
+            return commit;
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw lastError;
+}
+async function taskTreeEntries(cwd, commit) {
+    return (await git(cwd, ["ls-tree", "-r", "-z", commit, "--", ".keiyaku/tasks"]))
         .split("\0")
         .filter(Boolean)
         .map((record) => {
@@ -70,47 +146,79 @@ function taskTreeEntries(cwd, commit) {
         return { mode, oid, path: record.slice(tab + 1) };
     });
 }
-export function reconcileTaskIndex(cwd, commit) {
-    const existing = git(cwd, ["ls-files", "-z", "--", ".keiyaku/tasks"])
-        .split("\0")
-        .filter(Boolean);
-    for (const file of existing)
-        git(cwd, ["update-index", "--force-remove", "--", file]);
-    for (const entry of taskTreeEntries(cwd, commit)) {
-        git(cwd, ["update-index", "--add", "--cacheinfo", `${entry.mode},${entry.oid},${entry.path}`]);
+/** Reconcile only settlement-owned task paths; never rewrite an unrelated index entry. */
+export async function reconcileTaskPathsetIndex(cwd, commit, paths) {
+    const entries = new Map((await taskTreeEntries(cwd, commit)).map((entry) => [entry.path, entry]));
+    for (const taskPath of paths) {
+        const entry = entries.get(taskPath);
+        if (entry) {
+            await git(cwd, ["update-index", "--add", "--cacheinfo", `${entry.mode},${entry.oid},${entry.path}`]);
+        }
+        else {
+            await git(cwd, ["update-index", "--force-remove", "--", taskPath]);
+        }
     }
 }
-export function refHead(cwd, ref) {
-    return git(cwd, ["rev-parse", ref]).trim();
+/** Task paths tracked by one authoritative commit, independent of the worktree index. */
+export async function trackedTaskPaths(cwd, commit) {
+    return (await taskTreeEntries(cwd, commit)).map((entry) => entry.path).sort();
 }
-export function readableRefHead(cwd, ref) {
-    const result = gitResult(cwd, ["rev-parse", ref]);
-    if (result.status !== 0)
-        return undefined;
-    return result.stdout.trim();
+export async function refHead(cwd, ref) {
+    return (await git(cwd, ["rev-parse", ref])).trim();
 }
-export function taskContractAtCommit(cwd, commit, id) {
+export async function taskContractAtCommit(cwd, commit, id) {
     const sourcePath = `.keiyaku/tasks/${id}.md`;
-    const result = gitResult(cwd, ["show", `${commit}:${sourcePath}`]);
+    const result = await gitResult(cwd, ["show", `${commit}:${sourcePath}`]);
     if (result.status !== 0)
         return undefined;
     return parseTaskDocument({ path: sourcePath, text: result.stdout }).contractId;
 }
+/** Bound task ids and their complete parent ancestry from the immutable bind base. */
+export async function taskSettlementOwnershipAtCommit(cwd, commit, contractId) {
+    const documents = new Map();
+    for (const entry of await taskTreeEntries(cwd, commit)) {
+        const text = await git(cwd, ["cat-file", "blob", entry.oid]);
+        const document = parseTaskDocument({ path: entry.path, text });
+        documents.set(document.id, document);
+    }
+    const taskIds = [...documents.values()]
+        .filter((document) => document.contractId === contractId)
+        .map((document) => document.id)
+        .sort();
+    const ownedIds = new Set();
+    for (const taskId of taskIds) {
+        let current = taskId;
+        while (current !== null) {
+            if (ownedIds.has(current))
+                break;
+            ownedIds.add(current);
+            const document = documents.get(current);
+            if (!document) {
+                throw new FlowError("INTERNAL_STATE", `bind base ${commit} lost task ${current} from the owned ancestry`);
+            }
+            current = document.parent;
+        }
+    }
+    return {
+        taskIds,
+        paths: [...ownedIds].map((id) => `.keiyaku/tasks/${id}.md`).sort(),
+    };
+}
 export async function updateBranch(input, deps) {
     if (deps.updateBranch)
         await deps.updateBranch(input);
     else
-        git(input.cwd, ["update-ref", input.ref, input.next, input.expected]);
+        await git(input.cwd, ["update-ref", input.ref, input.next, input.expected]);
 }
 export async function publishForwardTaskBoardCommit(input, deps) {
     let lastError;
     for (let attempt = 0; attempt < 4; attempt += 1) {
-        const parent = refHead(input.cwd, input.ref);
-        const commit = createTaskBoardCommit({ ...input, parent });
+        const parent = await refHead(input.cwd, input.ref);
+        const commit = await createTaskBoardCommit({ ...input, parent });
         try {
             await updateBranch({ cwd: input.cwd, ref: input.ref, next: commit, expected: parent }, deps);
             try {
-                reconcileTaskIndex(input.cwd, commit);
+                await reconcileTaskPathsetIndex(input.cwd, commit, input.paths);
             }
             catch { /* the forward branch fact remains authoritative */ }
             return commit;
@@ -121,32 +229,32 @@ export async function publishForwardTaskBoardCommit(input, deps) {
     }
     throw lastError;
 }
-function treeWithoutTasks(cwd, commit, gitDir) {
+async function treeWithoutTasks(cwd, commit, gitDir) {
     const temporaryDirectory = fs.mkdtempSync(path.join(gitDir, "keiyaku-landing-index-"));
     const env = { GIT_INDEX_FILE: path.join(temporaryDirectory, "index") };
     try {
-        git(cwd, ["read-tree", commit], undefined, env);
-        git(cwd, ["rm", "-r", "--cached", "-f", "--ignore-unmatch", "--", ".keiyaku/tasks"], undefined, env);
-        return git(cwd, ["write-tree"], undefined, env).trim();
+        await git(cwd, ["read-tree", commit], undefined, env);
+        await git(cwd, ["rm", "-r", "--cached", "-f", "--ignore-unmatch", "--", ".keiyaku/tasks"], undefined, env);
+        return (await git(cwd, ["write-tree"], undefined, env)).trim();
     }
     finally {
         fs.rmSync(temporaryDirectory, { recursive: true, force: true });
     }
 }
-function composeLandingTree(input) {
-    const baseTree = treeWithoutTasks(input.cwd, input.base, input.gitDir);
-    const targetTree = treeWithoutTasks(input.cwd, input.target, input.gitDir);
-    const deliveryTree = treeWithoutTasks(input.cwd, input.delivery, input.gitDir);
+export async function composeLandingTree(input) {
+    const baseTree = await treeWithoutTasks(input.cwd, input.base, input.gitDir);
+    const targetTree = await treeWithoutTasks(input.cwd, input.target, input.gitDir);
+    const deliveryTree = await treeWithoutTasks(input.cwd, input.delivery, input.gitDir);
     let mergedTree;
     try {
-        mergedTree = git(input.cwd, [
+        mergedTree = (await git(input.cwd, [
             "merge-tree",
             "--write-tree",
             "--merge-base",
             baseTree,
             targetTree,
             deliveryTree,
-        ]).trim();
+        ])).trim();
     }
     catch (error) {
         throw new FlowError("CLOSE_MERGE_CONFLICT", "claim merge conflict outside task board", { cause: error });
@@ -154,43 +262,126 @@ function composeLandingTree(input) {
     const temporaryDirectory = fs.mkdtempSync(path.join(input.gitDir, "keiyaku-landing-index-"));
     const env = { GIT_INDEX_FILE: path.join(temporaryDirectory, "index") };
     try {
-        git(input.cwd, ["read-tree", mergedTree], undefined, env);
-        git(input.cwd, ["rm", "-r", "--cached", "-f", "--ignore-unmatch", "--", ".keiyaku/tasks"], undefined, env);
+        await git(input.cwd, ["read-tree", mergedTree], undefined, env);
+        // merge-tree deliberately excluded task paths. Restore the target board as
+        // the inherited baseline, then overlay only settlement-authorized writes.
+        for (const entry of await taskTreeEntries(input.cwd, input.target)) {
+            await git(input.cwd, [
+                "update-index",
+                "--add",
+                "--cacheinfo",
+                `${entry.mode},${entry.oid},${entry.path}`,
+            ], undefined, env);
+        }
         for (const source of input.sources) {
-            const oid = git(input.cwd, ["hash-object", "-w", "--stdin"], source.text).trim();
-            git(input.cwd, [
+            const oid = (await git(input.cwd, ["hash-object", "-w", "--stdin"], source.text)).trim();
+            await git(input.cwd, [
                 "update-index",
                 "--add",
                 "--cacheinfo",
                 `100644,${oid},${boardPath(input.root, source)}`,
             ], undefined, env);
         }
-        return git(input.cwd, ["write-tree"], undefined, env).trim();
+        return (await git(input.cwd, ["write-tree"], undefined, env)).trim();
     }
     finally {
         fs.rmSync(temporaryDirectory, { recursive: true, force: true });
     }
 }
-export function createLandingCommit(input) {
-    const tree = composeLandingTree(input);
-    return git(input.cwd, [
+function landingCommitMessage(contractId, targetBranch) {
+    return `keiyaku: claim ${contractId}\n\nMerge contract ${contractId} into ${targetBranch}.\n`;
+}
+async function isAncestor(cwd, ancestor, descendant) {
+    return (await gitResult(cwd, ["merge-base", "--is-ancestor", ancestor, descendant])).status === 0;
+}
+export async function taskSourcesAtCommit(cwd, root, commit, paths) {
+    const sources = [];
+    for (const sourcePath of paths) {
+        const result = await gitResult(cwd, ["show", `${commit}:${sourcePath}`]);
+        if (result.status !== 0)
+            return undefined;
+        sources.push({ path: path.join(root, ...sourcePath.split("/")), text: result.stdout });
+    }
+    return sources;
+}
+/**
+ * Find the durable landing receipt on the target's first-parent history.
+ * Equivalent trees and lookalike messages are insufficient: the commit must
+ * have our parent shape, settle every bind-base-owned task, and exactly match
+ * a recomposed landing tree over its own first parent.
+ */
+export async function findAcceptedLandingCommit(input) {
+    const commits = (await git(input.cwd, ["rev-list", "--first-parent", input.target, `^${input.base}`]))
+        .trim()
+        .split("\n")
+        .filter(Boolean);
+    for (const commit of commits) {
+        const message = await git(input.cwd, ["show", "-s", "--format=%B", commit]);
+        if (message.trimEnd() !== landingCommitMessage(input.contractId, input.targetBranch).trimEnd())
+            continue;
+        const record = (await git(input.cwd, ["rev-list", "--parents", "-n", "1", commit])).trim().split(/\s+/);
+        const parents = record.slice(1);
+        const parentShapeAccepted = parents.length === 2
+            ? parents[1] === input.delivery
+            : parents.length === 1 && await isAncestor(input.cwd, input.delivery, parents[0]);
+        if (!parentShapeAccepted)
+            continue;
+        const sources = await taskSourcesAtCommit(input.cwd, input.root, commit, input.ownedPaths);
+        if (!sources)
+            continue;
+        let settled = false;
+        try {
+            const sourceByPath = new Map(sources.map((source) => [boardPath(input.root, source), source]));
+            settled = input.settledPaths.every((settledPath) => {
+                const source = sourceByPath.get(settledPath);
+                if (!source)
+                    return false;
+                const document = parseTaskDocument(source);
+                return document.state === "done" && document.contractId === undefined;
+            });
+        }
+        catch {
+            // A malformed lookalike is not this operation's durable receipt.
+        }
+        if (!settled)
+            continue;
+        const expectedTree = await composeLandingTree({
+            cwd: input.cwd,
+            gitDir: input.gitDir,
+            root: input.root,
+            base: input.base,
+            target: parents[0],
+            delivery: input.delivery,
+            sources,
+        });
+        const actualTree = (await git(input.cwd, ["rev-parse", `${commit}^{tree}`])).trim();
+        if (actualTree === expectedTree)
+            return commit;
+    }
+    return undefined;
+}
+export async function containsCommit(cwd, ancestor, descendant) {
+    return await isAncestor(cwd, ancestor, descendant);
+}
+/** Create the landing commit over a previously composed candidate tree. */
+export async function createLandingCommit(input) {
+    // Once delivery is already reachable from target, a single-parent landing
+    // records this claim without fabricating a redundant merge parent.
+    const parents = input.target === input.delivery || await isAncestor(input.cwd, input.delivery, input.target)
+        ? ["-p", input.target]
+        : ["-p", input.target, "-p", input.delivery];
+    return (await git(input.cwd, [
         "commit-tree",
-        tree,
-        "-p",
-        input.target,
-        "-p",
-        input.delivery,
+        input.tree,
+        ...parents,
         "-m",
         `keiyaku: claim ${input.contractId}`,
         "-m",
         `Merge contract ${input.contractId} into ${input.targetBranch}.`,
-    ]).trim();
-}
-export function containsCommit(cwd, ancestor, descendant) {
-    return gitResult(cwd, ["merge-base", "--is-ancestor", ancestor, descendant]).status === 0;
+    ])).trim();
 }
-export function updateTargetRef(cwd, ref, next, expected) {
-    git(cwd, ["update-ref", ref, next, expected]);
+export async function updateTargetRef(cwd, ref, next, expected) {
+    await git(cwd, ["update-ref", ref, next, expected]);
 }
 export function sameTaskSourceBytes(root, left, right) {
     const snapshot = (sources) => new Map(sources.map((source) => [boardPath(root, source), source.text]));