@astrosheep/keiyaku 4.0.0 → 4.0.2

package/build/src/git/admission.js

@@ -1,8 +1,8 @@
-import { encodeEntry, } from "../core/facts/codec.js";
-import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, updateGitTree, updateRefsAtomically, writeBlob, writeCommit, } from "./repository.js";
-import { contractJournalPath, gitObjectIdForSnapshot, mintContractHead, mintSnapshotId, } from "./identity.js";
+import { decodeJournal, encodeEntry, } from "../core/facts/codec.js";
+import { GIT_FORMAT_BYTES, GIT_FORMAT_PATH, GIT_REF, updateGitTreeFromFrozenDirectories, updateRefsAtomically, writeBlob, writeCommit, } from "./repository.js";
+import { contractJournalPath, contractJournalPaths, gitObjectIdForSnapshot, mintContractHead, mintSnapshotId, } from "./identity.js";
 import { validPath } from "./tree.js";
-const CONTRACT_JOURNAL_PATH = /^contracts\/[0-9a-f]{2}\/[0-9a-f]{2}\/[0-9a-f]{60}\.jsonl$/u;
+const CONTRACT_JOURNAL_PATH = /^contracts\/(?:active|terminal)\/[0-9a-f]{2}\/[0-9a-f]{2}\/[0-9a-f]{60}\.jsonl$/u;
 function assertAppendStructure(appends) {
     const seen = new Set();
     for (const append of appends) {
@@ -20,7 +20,7 @@ function assertAppendStructure(appends) {
     return appends;
 }
 function assertCompanionStructure(companions, appends) {
-    const reserved = new Set([GIT_FORMAT_PATH, ...appends.map((append) => contractJournalPath(append.contractId))]);
+    const reserved = new Set([GIT_FORMAT_PATH, ...appends.flatMap((append) => contractJournalPaths(append.contractId))]);
     const seen = new Set();
     for (const companion of companions) {
         if (!companion || typeof companion !== "object")
@@ -39,49 +39,59 @@ function assertCompanionStructure(companions, appends) {
 }
 function readCanonicalJournal(admission, id) {
     const snapshot = admission.snapshot;
-    const path = contractJournalPath(id);
+    const matches = contractJournalPaths(id).filter((path) => snapshot.paths.has(path));
+    if (matches.length > 1)
+        throw new Error(`duplicate contract journal identity: ${id}`);
+    const path = matches[0];
+    if (path === undefined)
+        return { bytes: Buffer.alloc(0), path: null };
     const entry = snapshot.paths.get(path);
-    if (entry === undefined)
-        return Buffer.alloc(0);
     if (entry.type !== "blob")
         throw new Error(`journal path is not a blob: ${path}`);
     const journal = admission.frozenJournalBytes.get(entry.oid);
     if (journal === undefined)
         throw new Error(`missing frozen journal bytes: ${path}`);
-    return journal;
+    return { bytes: journal, path };
 }
-function buildOffer(repository, admission, appends, companions) {
+async function buildOffer(repository, admission, appends, companions) {
     const snapshot = admission.snapshot;
     const changes = new Map();
     const heads = {};
     if (snapshot.commit === null) {
-        changes.set(GIT_FORMAT_PATH, { oid: writeBlob(repository, GIT_FORMAT_BYTES), mode: "100644", type: "blob" });
+        changes.set(GIT_FORMAT_PATH, { oid: await writeBlob(repository, GIT_FORMAT_BYTES), mode: "100644", type: "blob" });
     }
     for (const companion of companions) {
         changes.set(companion.path, {
-            oid: writeBlob(repository, companion.bytes),
+            oid: await writeBlob(repository, companion.bytes),
             mode: "100644",
             type: "blob",
         });
     }
     for (const append of appends) {
-        let journal = readCanonicalJournal(admission, append.contractId);
+        const current = readCanonicalJournal(admission, append.contractId);
+        let journal = current.bytes;
         for (const entry of append.entries)
             journal = Buffer.concat([journal, Buffer.from(encodeEntry(entry))]);
-        const blob = writeBlob(repository, journal);
-        changes.set(contractJournalPath(append.contractId), { oid: blob, mode: "100644", type: "blob" });
+        const blob = await writeBlob(repository, journal);
+        const entries = decodeJournal(journal.toString("utf8"));
+        const terminal = entries.some((entry) => entry.kind === "claimed" || entry.kind === "abandoned");
+        const destination = contractJournalPath(append.contractId, terminal ? "terminal" : "active");
+        if (current.path !== null && current.path !== destination)
+            changes.set(current.path, null);
+        changes.set(destination, { oid: blob, mode: "100644", type: "blob" });
         heads[append.contractId] = mintContractHead(blob);
     }
     return { changes, heads };
 }
-function publishOffer(repository, snapshot, target, changes) {
-    const gitTree = updateGitTree(repository, snapshot.tree, changes);
-    const gitCommit = mintSnapshotId(writeCommit({
+async function publishOffer(repository, admission, target, changes, assertions) {
+    const { snapshot } = admission;
+    const gitTree = await updateGitTreeFromFrozenDirectories(repository, snapshot.tree, admission.treeDirectories, changes);
+    const gitCommit = mintSnapshotId(await writeCommit({
         repository,
         tree: gitTree,
         parent: snapshot.commit,
     }));
-    return updateRefsAtomically(repository, [
+    return await updateRefsAtomically(repository, [
         { ref: GIT_REF, newOid: gitObjectIdForSnapshot(gitCommit), expectedOid: snapshot.commit },
         ...(target === null
             ? []
@@ -90,17 +100,17 @@ function publishOffer(repository, snapshot, target, changes) {
                     newOid: gitObjectIdForSnapshot(target.newOid),
                     expectedOid: gitObjectIdForSnapshot(target.expectedOid),
                 }]),
-    ]);
+    ], assertions);
 }
-export function admit(repository, offer, admission) {
+export async function admit(repository, offer, admission, assertions = []) {
     if (!Array.isArray(offer.facts) || offer.facts.length === 0) {
         throw new Error("facts must be a nonempty array");
     }
     const appends = assertAppendStructure(offer.facts);
     const companions = assertCompanionStructure(offer.companions ?? [], appends);
     const target = offer.target ?? null;
-    const attempt = buildOffer(repository, admission, appends, companions);
-    const publication = publishOffer(repository, admission.snapshot, target, attempt.changes);
+    const attempt = await buildOffer(repository, admission, appends, companions);
+    const publication = await publishOffer(repository, admission, target, attempt.changes, assertions);
     if (publication.kind === "published") {
         return {
             kind: "accepted",

package/build/src/git/hooks.d.ts

@@ -1,3 +1,4 @@
+import { type Settings } from "../settings.js";
 export type HookCommand = Readonly<{
     argv: readonly string[];
     timeoutMs: number;
@@ -28,7 +29,21 @@ export type WorktreeHookLag = Readonly<{
     failure: HookFailure;
 }>;
 type HookPhase = "create" | "destroy";
+export declare function worktreeHooksFrom(input: Readonly<{
+    settings: Settings;
+}>): WorktreeHooks;
 export declare function hookMarkerPath(administrationDirectory: string): string;
+export type HookCommandRun = Readonly<{
+    kind: "ok";
+}> | Readonly<{
+    kind: "cancelled";
+}> | Readonly<{
+    kind: "failed";
+    command: number;
+    failure: HookFailure;
+}>;
+/** Execute an ordered command list without lifecycle state. Scratch owns this policy. */
+export declare function runHookCommands(worktree: string, commands: readonly HookCommand[], signal?: AbortSignal): Promise<HookCommandRun>;
 export declare function runCreateHooks(worktree: string, administrationDirectory: string, hooks: WorktreeHooks, retryHooks: boolean): Promise<WorktreeHookLag | null>;
 export declare function runDestroyHooks(worktree: string, administrationDirectory: string, hooks: WorktreeHooks, retryHooks: boolean): Promise<WorktreeHookLag | null>;
 export {};

package/build/src/git/hooks.js

@@ -1,13 +1,49 @@
-import { mkdirSync, readFileSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { replaceFileDurably } from "../coordination/durable-file.js";
 import { acquireSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
 import { runProcess, runProcessToExit } from "../runtime/proc/run.js";
+import { SettingsError } from "../settings.js";
 const MARKER_VERSION = 1;
 function object(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+export function worktreeHooksFrom(input) {
+    if (!object(input))
+        throw new TypeError("worktreeHooksFrom input must be an object");
+    const view = input.settings.namespace("worktree");
+    if (view.kind === "failed") {
+        throw new SettingsError(view.failures.map((failure) => `${failure.scope}: ${failure.diagnostic}`).join("; "));
+    }
+    for (const entry of view.entries) {
+        if (entry.name !== "create" && entry.name !== "destroy")
+            throw new SettingsError(`worktree has unknown entry: ${entry.name}`);
+    }
+    const commands = (phase) => {
+        const selected = view.entries.find((entry) => entry.name === phase);
+        if (selected === undefined)
+            return Object.freeze([]);
+        if (!Array.isArray(selected.value))
+            throw new SettingsError(`worktree.${phase} must be an array`);
+        return Object.freeze(selected.value.map((item, index) => {
+            if (!object(item))
+                throw new SettingsError(`worktree.${phase}[${index}] must be an object`);
+            const coordinate = `worktree.${phase}[${index}]`;
+            exactKeys(item, ["argv", "timeoutMs"], coordinate);
+            if (!Array.isArray(item.argv) || item.argv.length === 0 || !item.argv.every((value) => typeof value === "string")) {
+                throw new SettingsError(`${coordinate}.argv must be a nonempty string array`);
+            }
+            if (item.argv[0].trim().length === 0)
+                throw new SettingsError(`${coordinate}.argv[0] must be nonblank`);
+            if (!Number.isSafeInteger(item.timeoutMs) || item.timeoutMs < 1 || item.timeoutMs > 2_147_483_647) {
+                throw new SettingsError(`${coordinate}.timeoutMs must be an integer from 1 through 2147483647`);
+            }
+            return Object.freeze({ argv: Object.freeze([...item.argv]), timeoutMs: item.timeoutMs });
+        }));
+    };
+    return Object.freeze({ create: commands("create"), destroy: commands("destroy") });
+}
 function exactKeys(value, keys, coordinate) {
     const actual = Object.keys(value).sort();
     const expected = [...keys].sort();
@@ -104,9 +140,9 @@ function decodeMarker(bytes) {
 export function hookMarkerPath(administrationDirectory) {
     return join(administrationDirectory, "keiyaku", "hooks.json");
 }
-function readMarker(administrationDirectory) {
+async function readMarker(administrationDirectory) {
     try {
-        return decodeMarker(readFileSync(hookMarkerPath(administrationDirectory), "utf8"));
+        return decodeMarker(await readFile(hookMarkerPath(administrationDirectory), "utf8"));
     }
     catch (error) {
         if (error.code === "ENOENT")
@@ -114,10 +150,10 @@ function readMarker(administrationDirectory) {
         throw error;
     }
 }
-function writeMarker(administrationDirectory, marker) {
+async function writeMarker(administrationDirectory, marker) {
     const path = hookMarkerPath(administrationDirectory);
-    mkdirSync(dirname(path), { recursive: true });
-    replaceFileDurably(path, `${JSON.stringify(marker)}\n`);
+    await mkdir(dirname(path), { recursive: true });
+    await replaceFileDurably(path, `${JSON.stringify(marker)}\n`);
 }
 function freshMarker(commands, createPending) {
     return {
@@ -139,6 +175,23 @@ function failedOutcome(outcome) {
     }
     return outcome;
 }
+/** Execute an ordered command list without lifecycle state. Scratch owns this policy. */
+export async function runHookCommands(worktree, commands, signal) {
+    for (const [command, value] of commands.entries()) {
+        const outcome = await runProcess({
+            argv: value.argv,
+            timeoutMs: value.timeoutMs,
+            cwd: worktree,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        if (outcome.kind === "cancelled")
+            return outcome;
+        const failure = failedOutcome(outcome);
+        if (failure !== null)
+            return { kind: "failed", command, failure };
+    }
+    return { kind: "ok" };
+}
 function withProgress(marker, phase, progress) {
     return { ...marker, [phase]: progress };
 }
@@ -174,7 +227,7 @@ async function executePendingCommand(input) {
         mode: "immediate",
     });
     try {
-        const marker = readMarker(input.administrationDirectory);
+        const marker = await readMarker(input.administrationDirectory);
         if (marker === null)
             throw new Error("worktree hook marker disappeared before execution");
         const progress = marker[input.phase];
@@ -183,13 +236,12 @@ async function executePendingCommand(input) {
         const command = marker.commands[input.phase][input.command];
         if (command === undefined)
             throw new Error("worktree hook marker pending index is out of range");
-        const failure = failedOutcome(await runProcess({
-            argv: command.argv,
-            timeoutMs: command.timeoutMs,
-            cwd: input.worktree,
-        }));
+        const result = await runHookCommands(input.worktree, [command]);
+        if (result.kind === "cancelled")
+            throw new Error("managed hook runner cancelled without a signal");
+        const failure = result.kind === "failed" ? result.failure : null;
         const next = input.command + 1;
-        writeMarker(input.administrationDirectory, withProgress(marker, input.phase, failure === null
+        await writeMarker(input.administrationDirectory, withProgress(marker, input.phase, failure === null
             ? next === marker.commands[input.phase].length ? { status: "ok" } : { status: "pending", next }
             : { status: "failed", command: input.command, failure }));
     }
@@ -216,14 +268,14 @@ async function runPendingCommand(input) {
         throw runnerFailure(outcome);
 }
 async function runPhase(worktree, administrationDirectory, hooks, phase, retryHooks) {
-    let marker = readMarker(administrationDirectory);
+    let marker = await readMarker(administrationDirectory);
     if (marker === null) {
         marker = freshMarker(hooks, phase === "create");
-        writeMarker(administrationDirectory, marker);
+        await writeMarker(administrationDirectory, marker);
     }
     let retryFailure = retryHooks && marker[phase].status === "failed";
     for (;;) {
-        marker = readMarker(administrationDirectory);
+        marker = await readMarker(administrationDirectory);
         if (marker === null)
             throw new Error("worktree hook marker disappeared during execution");
         const progress = marker[phase];
@@ -234,11 +286,11 @@ async function runPhase(worktree, administrationDirectory, hooks, phase, retryHo
                 return { kind: "worktree-hook-failed", phase, path: worktree, command: progress.command, failure: progress.failure };
             }
             retryFailure = false;
-            writeMarker(administrationDirectory, withProgress(marker, phase, { status: "pending", next: progress.command }));
+            await writeMarker(administrationDirectory, withProgress(marker, phase, { status: "pending", next: progress.command }));
             continue;
         }
         if (progress.next === marker.commands[phase].length) {
-            writeMarker(administrationDirectory, withProgress(marker, phase, { status: "ok" }));
+            await writeMarker(administrationDirectory, withProgress(marker, phase, { status: "ok" }));
             continue;
         }
         await runPendingCommand({ administrationDirectory, worktree, phase, command: progress.next });

package/build/src/git/identity.d.ts

@@ -4,7 +4,11 @@ export type GitObjectId = string & {
     readonly [gitObjectIdBrand]: "GitObjectId";
 };
 export declare function contractLocator(contract: ContractId): string;
-export declare function contractJournalPath(contract: ContractId): string;
+export declare function gitRefLocator(ref: string): string;
+export declare function contractPhysicalName(contract: ContractId): string;
+export type ContractJournalClass = "active" | "terminal";
+export declare function contractJournalPath(contract: ContractId, journalClass?: ContractJournalClass): string;
+export declare function contractJournalPaths(contract: ContractId): readonly string[];
 export declare function gitObjectId(value: string, label?: string): GitObjectId;
 export declare function mintSnapshotId(value: string): SnapshotId;
 export declare function mintChangeId(value: string): ChangeId;

package/build/src/git/identity.js

@@ -1,13 +1,32 @@
 import { createHash } from "node:crypto";
 import { changeId, contractHead, contractId, snapshotId, } from "../core/facts/types.js";
 const GIT_OBJECT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+function locator(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
 export function contractLocator(contract) {
-    const id = contractId(contract);
-    return createHash("sha256").update(id, "utf8").digest("hex");
+    return locator(contractId(contract));
+}
+export function gitRefLocator(ref) {
+    if (ref.length === 0)
+        throw new Error("Git ref locator input must be nonempty");
+    return locator(ref);
+}
+export function contractPhysicalName(contract) {
+    return contractId(contract).replace("/", "-");
 }
-export function contractJournalPath(contract) {
+function contractJournalSuffix(contract) {
     const digest = contractLocator(contract);
-    return `contracts/${digest.slice(0, 2)}/${digest.slice(2, 4)}/${digest.slice(4)}.jsonl`;
+    return `${digest.slice(0, 2)}/${digest.slice(2, 4)}/${digest.slice(4)}.jsonl`;
+}
+export function contractJournalPath(contract, journalClass = "active") {
+    return `contracts/${journalClass}/${contractJournalSuffix(contract)}`;
+}
+export function contractJournalPaths(contract) {
+    return [
+        contractJournalPath(contract, "active"),
+        contractJournalPath(contract, "terminal"),
+    ];
 }
 export function gitObjectId(value, label = "Git object ID") {
     if (!GIT_OBJECT_ID.test(value))

package/build/src/git/integration.d.ts

@@ -0,0 +1,48 @@
+import type { Preparation } from "../core/decide.js";
+import type { ChangeId, ContractCoordinates, ContractId, SnapshotId } from "../core/facts/types.js";
+import { type GitObjectId } from "./identity.js";
+import { type GitRepository } from "./repository.js";
+import type { TenderCapture } from "./tender.js";
+declare const REQUIRED_GIT: "2.38";
+export type IntegrationPreparationRefusal = Readonly<{
+    kind: "integration-failed";
+    contractId: ContractId;
+    reason: "not-based-on-target" | "unrelated-histories" | "conflict";
+    targetHead: SnapshotId;
+    conflictPaths?: readonly string[];
+}> | Readonly<{
+    kind: "integration-unsupported";
+    contractId: ContractId;
+    requiredGit: typeof REQUIRED_GIT;
+}>;
+export type IntegrationCoordinates = Readonly<{
+    contractId: ContractId;
+    coordinates: ContractCoordinates;
+}>;
+export type IntegrationPlan = Readonly<{
+    predecessor: SnapshotId;
+    tree: GitObjectId;
+}>;
+/** Mint the one worktree-content identity shared by review and delivery. */
+export declare function worktreeChangeId(repository: GitRepository, input: IntegrationCoordinates, tender: TenderCapture): Promise<ChangeId>;
+/** Materialize the exact integration tree against its observed predecessor. */
+export declare function materializeIntegrationSnapshot(repository: GitRepository, tree: GitObjectId, parent: SnapshotId, input: Readonly<{
+    contractId: ContractId;
+    title: string;
+    message?: string;
+}>): Promise<SnapshotId>;
+export declare function planIntegration(repository: GitRepository, input: IntegrationCoordinates, tender: TenderCapture, requireBranchesToBeUpToDate: boolean): Promise<Preparation<IntegrationPlan, Readonly<{
+    kind: "target-missing";
+    contractId: ContractId;
+}> | IntegrationPreparationRefusal>>;
+export type DeliveryDiffScope = Readonly<{
+    filesChanged: number;
+    insertions: number;
+    deletions: number;
+    paths?: readonly string[];
+}>;
+/** Compute predecessor-to-candidate scope from the exact integration trees. */
+export declare function readDeliveryScope(repository: GitRepository, predecessor: SnapshotId, candidate: SnapshotId, includePaths: boolean): Promise<DeliveryDiffScope>;
+/** Read a recorded integration pair's patch, or null when Git no longer has it. */
+export declare function readDeliveryDiff(repository: GitRepository, predecessor: SnapshotId, candidate: SnapshotId): Promise<string | null>;
+export {};

package/build/src/git/integration.js

@@ -0,0 +1,250 @@
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { gitObjectId, gitObjectIdForSnapshot, mintChangeId, mintSnapshotId } from "./identity.js";
+import { decodeGitNameOnly, decodeGitNumstat, GitPlumbingError, readRef, runGit, runGitWithEnvironment, } from "./repository.js";
+const REQUIRED_GIT = "2.38";
+async function runAllowingNonzero(repository, args, input) {
+    try {
+        return { stdout: await runGit(repository, args, input), stderr: Buffer.alloc(0), status: 0 };
+    }
+    catch (error) {
+        if (!(error instanceof GitPlumbingError))
+            throw error;
+        return { stdout: error.stdout, stderr: error.stderr, status: error.status };
+    }
+}
+/** Mint the one worktree-content identity shared by review and delivery. */
+export async function worktreeChangeId(repository, input, tender) {
+    const patch = await runGit(repository, [
+        "-c", "core.quotePath=false",
+        "-c", "core.abbrev=40",
+        "-c", "diff.algorithm=myers",
+        "-c", "diff.renames=false",
+        "-c", "diff.indentHeuristic=false",
+        "-c", "diff.suppressBlankEmpty=false",
+        "diff",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--no-indent-heuristic",
+        "--no-renames",
+        "--full-index",
+        "--binary",
+        "--no-color",
+        "--diff-algorithm=myers",
+        "--unified=3",
+        "--src-prefix=a/",
+        "--dst-prefix=b/",
+        "--inter-hunk-context=0",
+        "--no-relative",
+        "--ignore-submodules=none",
+        "--submodule=short",
+        gitObjectIdForSnapshot(input.coordinates.start),
+        tender.tree,
+    ]);
+    const id = (await runGit(repository, ["patch-id", "--verbatim"], patch)).toString("utf8").trim().split(/\s/, 1)[0] ?? "";
+    return mintChangeId(id === "" ? "0000000000000000000000000000000000000000" : id);
+}
+/** Materialize the exact integration tree against its observed predecessor. */
+export async function materializeIntegrationSnapshot(repository, tree, parent, input) {
+    const commit = (await runGitWithEnvironment(repository, ["commit-tree", tree, "-p", gitObjectIdForSnapshot(parent)], `${input.message ?? `${input.contractId}: ${input.title}`}\n\nKeiyaku-Contract: ${input.contractId}\n`, {
+        GIT_AUTHOR_NAME: "Keiyaku",
+        GIT_AUTHOR_EMAIL: "keiyaku@localhost",
+        GIT_COMMITTER_NAME: "Keiyaku",
+        GIT_COMMITTER_EMAIL: "keiyaku@localhost",
+        GIT_AUTHOR_DATE: "Thu, 01 Jan 1970 00:00:00 +0000",
+        GIT_COMMITTER_DATE: "Thu, 01 Jan 1970 00:00:00 +0000",
+    })).toString("utf8").trim();
+    return mintSnapshotId(commit);
+}
+async function isAncestor(repository, ancestor, descendant) {
+    const result = await runAllowingNonzero(repository, [
+        "merge-base",
+        "--is-ancestor",
+        gitObjectIdForSnapshot(ancestor),
+        gitObjectIdForSnapshot(descendant),
+    ]);
+    if (result.status === 0)
+        return true;
+    if (result.status === 1)
+        return false;
+    throw new GitPlumbingError({
+        stderr: result.stderr,
+        status: result.status,
+        message: "git merge-base --is-ancestor failed",
+    });
+}
+async function commonAncestor(repository, left, right) {
+    const result = await runAllowingNonzero(repository, [
+        "merge-base",
+        gitObjectIdForSnapshot(left),
+        gitObjectIdForSnapshot(right),
+    ]);
+    if (result.status === 1)
+        return null;
+    if (result.status !== 0) {
+        throw new GitPlumbingError({
+            stderr: result.stderr,
+            status: result.status,
+            message: "git merge-base failed",
+        });
+    }
+    return mintSnapshotId(result.stdout.toString("utf8").trim());
+}
+async function supportsMergeTree(repository) {
+    return (await runAllowingNonzero(repository, ["merge-tree", "--write-tree", "--stdin"], "")).status === 0;
+}
+function nulFields(output) {
+    const fields = output.toString("utf8").split("\0");
+    if (fields.at(-1) !== "")
+        throw new Error("Git merge-tree output is not NUL terminated");
+    return fields.slice(0, -1);
+}
+async function mergedTree(repository, contractId, base, targetHead, tenderTree) {
+    if (!(await supportsMergeTree(repository))) {
+        return { kind: "refused", refusal: { kind: "integration-unsupported", contractId, requiredGit: REQUIRED_GIT } };
+    }
+    const result = await runAllowingNonzero(repository, [
+        "merge-tree",
+        "--write-tree",
+        "--no-messages",
+        "-z",
+        "--name-only",
+        "--merge-base",
+        gitObjectIdForSnapshot(base),
+        gitObjectIdForSnapshot(targetHead),
+        tenderTree,
+    ]);
+    const fields = nulFields(result.stdout);
+    if (result.status === 0) {
+        if (fields.length !== 1)
+            throw new Error("successful Git merge-tree output has unexpected fields");
+        return { kind: "prepared", data: gitObjectId(fields[0], "integration tree") };
+    }
+    if (result.status === 1) {
+        if (fields.length < 2)
+            throw new Error("conflicted Git merge-tree output is missing paths");
+        return {
+            kind: "refused",
+            refusal: {
+                kind: "integration-failed",
+                contractId,
+                reason: "conflict",
+                targetHead,
+                conflictPaths: Object.freeze([...new Set(fields.slice(1))].sort()),
+            },
+        };
+    }
+    throw new GitPlumbingError({
+        stderr: result.stderr,
+        status: result.status,
+        message: "git merge-tree --write-tree failed",
+    });
+}
+export async function planIntegration(repository, input, tender, requireBranchesToBeUpToDate) {
+    const target = input.coordinates.target;
+    if (target === undefined) {
+        return {
+            kind: "prepared",
+            data: {
+                predecessor: input.coordinates.start,
+                tree: tender.tree,
+            },
+        };
+    }
+    const observed = await readRef(repository, target);
+    if (observed === null) {
+        return { kind: "refused", refusal: { kind: "target-missing", contractId: input.contractId } };
+    }
+    const targetHead = mintSnapshotId(observed);
+    let tree;
+    if (requireBranchesToBeUpToDate) {
+        if (!(await isAncestor(repository, targetHead, tender.head))) {
+            return {
+                kind: "refused",
+                refusal: {
+                    kind: "integration-failed",
+                    contractId: input.contractId,
+                    reason: "not-based-on-target",
+                    targetHead,
+                },
+            };
+        }
+        tree = tender.tree;
+    }
+    else {
+        const base = await commonAncestor(repository, tender.head, targetHead);
+        if (base === null) {
+            return {
+                kind: "refused",
+                refusal: {
+                    kind: "integration-failed",
+                    contractId: input.contractId,
+                    reason: "unrelated-histories",
+                    targetHead,
+                },
+            };
+        }
+        const merged = await mergedTree(repository, input.contractId, base, targetHead, tender.tree);
+        if (merged.kind === "refused")
+            return merged;
+        tree = merged.data;
+    }
+    return {
+        kind: "prepared",
+        data: {
+            predecessor: targetHead,
+            tree,
+        },
+    };
+}
+async function deliverySnapshotAvailability(repository, predecessor, candidate) {
+    const objects = [gitObjectIdForSnapshot(predecessor), gitObjectIdForSnapshot(candidate)];
+    const types = (await runGit(repository, ["cat-file", "--batch-check=%(objectname) %(objecttype)"], `${objects.join("\n")}\n`)).toString("ascii").trimEnd().split("\n").map((record) => record.split(" ")[1]);
+    if (types.includes("missing"))
+        return "unavailable";
+    if (types.some((type) => type !== "commit")) {
+        throw new AuthorityCorruptionError("recorded delivery snapshot is not a Git commit");
+    }
+    return "available";
+}
+/** Compute predecessor-to-candidate scope from the exact integration trees. */
+export async function readDeliveryScope(repository, predecessor, candidate, includePaths) {
+    const scope = decodeGitNumstat(await runGit(repository, [
+        "diff",
+        "--numstat",
+        "-z",
+        gitObjectIdForSnapshot(predecessor),
+        gitObjectIdForSnapshot(candidate),
+    ]));
+    if (!includePaths)
+        return scope;
+    return {
+        ...scope,
+        paths: decodeGitNameOnly(await runGit(repository, [
+            "diff",
+            "--name-only",
+            "--no-renames",
+            "-z",
+            gitObjectIdForSnapshot(predecessor),
+            gitObjectIdForSnapshot(candidate),
+        ])),
+    };
+}
+/** Read a recorded integration pair's patch, or null when Git no longer has it. */
+export async function readDeliveryDiff(repository, predecessor, candidate) {
+    if (await deliverySnapshotAvailability(repository, predecessor, candidate) === "unavailable")
+        return null;
+    try {
+        return (await runGit(repository, [
+            "diff",
+            "--no-ext-diff",
+            "--no-color",
+            gitObjectIdForSnapshot(predecessor),
+            gitObjectIdForSnapshot(candidate),
+        ])).toString("utf8");
+    }
+    catch (error) {
+        if (await deliverySnapshotAvailability(repository, predecessor, candidate) === "unavailable")
+            return null;
+        throw error;
+    }
+}