@astrosheep/keiyaku 2.9.13 → 4.0.1

package/build/src/git/hooks.js

@@ -0,0 +1,310 @@
+import { mkdirSync, readFileSync } from "node:fs";
+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();
+    if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+        throw new Error(`${coordinate} has invalid fields`);
+    }
+}
+function decodeCommand(value, coordinate) {
+    if (!object(value))
+        throw new Error(`${coordinate} must be an object`);
+    exactKeys(value, ["argv", "timeoutMs"], coordinate);
+    if (!Array.isArray(value.argv) || value.argv.length === 0 || !value.argv.every((item) => typeof item === "string")) {
+        throw new Error(`${coordinate}.argv must be a nonempty string array`);
+    }
+    if (value.argv[0].trim().length === 0)
+        throw new Error(`${coordinate}.argv[0] must be nonblank`);
+    if (!Number.isSafeInteger(value.timeoutMs) || value.timeoutMs < 1 || value.timeoutMs > 2_147_483_647) {
+        throw new Error(`${coordinate}.timeoutMs is invalid`);
+    }
+    return { argv: value.argv, timeoutMs: value.timeoutMs };
+}
+function decodeCommands(value, coordinate) {
+    if (!Array.isArray(value))
+        throw new Error(`${coordinate} must be an array`);
+    return value.map((item, index) => decodeCommand(item, `${coordinate}[${index}]`));
+}
+function decodeFailure(value, coordinate) {
+    if (!object(value) || typeof value.kind !== "string")
+        throw new Error(`${coordinate} is invalid`);
+    switch (value.kind) {
+        case "exit":
+            exactKeys(value, ["kind", "code", "stdout", "stderr", "truncated"], coordinate);
+            if (!Number.isInteger(value.code) || typeof value.stdout !== "string" || typeof value.stderr !== "string" || typeof value.truncated !== "boolean") {
+                throw new Error(`${coordinate} is invalid`);
+            }
+            return { kind: "exit", code: value.code, stdout: value.stdout, stderr: value.stderr, truncated: value.truncated };
+        case "timeout":
+        case "unknown-exit":
+            exactKeys(value, ["kind"], coordinate);
+            return { kind: value.kind };
+        case "spawn-error":
+            exactKeys(value, ["kind", "diagnostic"], coordinate);
+            if (typeof value.diagnostic !== "string")
+                throw new Error(`${coordinate}.diagnostic must be a string`);
+            return { kind: "spawn-error", diagnostic: value.diagnostic };
+        default:
+            throw new Error(`${coordinate}.kind is invalid`);
+    }
+}
+function decodeProgress(value, commands, coordinate) {
+    if (!object(value) || typeof value.status !== "string")
+        throw new Error(`${coordinate} is invalid`);
+    if (value.status === "ok") {
+        exactKeys(value, ["status"], coordinate);
+        return { status: "ok" };
+    }
+    if (value.status === "pending") {
+        exactKeys(value, ["status", "next"], coordinate);
+        if (!Number.isInteger(value.next) || value.next < 0 || value.next > commands) {
+            throw new Error(`${coordinate}.next is invalid`);
+        }
+        return { status: "pending", next: value.next };
+    }
+    if (value.status === "failed") {
+        exactKeys(value, ["status", "command", "failure"], coordinate);
+        if (!Number.isInteger(value.command) || value.command < 0 || value.command >= commands) {
+            throw new Error(`${coordinate}.command is invalid`);
+        }
+        return { status: "failed", command: value.command, failure: decodeFailure(value.failure, `${coordinate}.failure`) };
+    }
+    throw new Error(`${coordinate}.status is invalid`);
+}
+function decodeMarker(bytes) {
+    const value = JSON.parse(bytes);
+    if (!object(value))
+        throw new Error("worktree hook marker must be an object");
+    exactKeys(value, ["version", "commands", "create", "destroy"], "worktree hook marker");
+    if (value.version !== MARKER_VERSION)
+        throw new Error(`worktree hook marker version must be ${MARKER_VERSION}`);
+    if (!object(value.commands))
+        throw new Error("worktree hook marker commands must be an object");
+    exactKeys(value.commands, ["create", "destroy"], "worktree hook marker commands");
+    const commands = {
+        create: decodeCommands(value.commands.create, "worktree hook marker commands.create"),
+        destroy: decodeCommands(value.commands.destroy, "worktree hook marker commands.destroy"),
+    };
+    return {
+        version: MARKER_VERSION,
+        commands,
+        create: decodeProgress(value.create, commands.create.length, "worktree hook marker create"),
+        destroy: decodeProgress(value.destroy, commands.destroy.length, "worktree hook marker destroy"),
+    };
+}
+export function hookMarkerPath(administrationDirectory) {
+    return join(administrationDirectory, "keiyaku", "hooks.json");
+}
+function readMarker(administrationDirectory) {
+    try {
+        return decodeMarker(readFileSync(hookMarkerPath(administrationDirectory), "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function writeMarker(administrationDirectory, marker) {
+    const path = hookMarkerPath(administrationDirectory);
+    mkdirSync(dirname(path), { recursive: true });
+    replaceFileDurably(path, `${JSON.stringify(marker)}\n`);
+}
+function freshMarker(commands, createPending) {
+    return {
+        version: MARKER_VERSION,
+        commands,
+        create: createPending ? { status: "pending", next: 0 } : { status: "ok" },
+        destroy: { status: "pending", next: 0 },
+    };
+}
+function failedOutcome(outcome) {
+    if (outcome.kind === "terminal") {
+        return outcome.code === 0 ? null : {
+            kind: "exit",
+            code: outcome.code,
+            stdout: outcome.stdout,
+            stderr: outcome.stderr,
+            truncated: outcome.truncated,
+        };
+    }
+    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 };
+}
+function hookExecutionLockPath(administrationDirectory) {
+    return join(administrationDirectory, "keiyaku", "hook-execution.sqlite");
+}
+function decodeRunnerInput(encoded) {
+    const value = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+    if (!object(value))
+        throw new Error("Hook runner input must be an object");
+    exactKeys(value, ["administrationDirectory", "worktree", "phase", "command"], "Hook runner input");
+    if (typeof value.administrationDirectory !== "string" || value.administrationDirectory.length === 0) {
+        throw new Error("Hook runner administrationDirectory must be nonempty");
+    }
+    if (typeof value.worktree !== "string" || value.worktree.length === 0) {
+        throw new Error("Hook runner worktree must be nonempty");
+    }
+    if (value.phase !== "create" && value.phase !== "destroy")
+        throw new Error("Hook runner phase is invalid");
+    if (!Number.isSafeInteger(value.command) || value.command < 0) {
+        throw new Error("Hook runner command must be a nonnegative safe integer");
+    }
+    return {
+        administrationDirectory: value.administrationDirectory,
+        worktree: value.worktree,
+        phase: value.phase,
+        command: value.command,
+    };
+}
+async function executePendingCommand(input) {
+    const held = await acquireSqliteTransactionLock({
+        path: hookExecutionLockPath(input.administrationDirectory),
+        mode: "immediate",
+    });
+    try {
+        const marker = readMarker(input.administrationDirectory);
+        if (marker === null)
+            throw new Error("worktree hook marker disappeared before execution");
+        const progress = marker[input.phase];
+        if (progress.status !== "pending" || progress.next !== input.command)
+            return;
+        const command = marker.commands[input.phase][input.command];
+        if (command === undefined)
+            throw new Error("worktree hook marker pending index is out of range");
+        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
+            ? next === marker.commands[input.phase].length ? { status: "ok" } : { status: "pending", next }
+            : { status: "failed", command: input.command, failure }));
+    }
+    finally {
+        held.close();
+    }
+}
+function runnerFailure(outcome) {
+    if (outcome.kind === "terminal") {
+        const detail = outcome.stderr.trim() || outcome.stdout.trim();
+        return new Error(detail.length === 0 ? `Hook runner exited ${outcome.code}` : `Hook runner exited ${outcome.code}: ${detail}`);
+    }
+    if (outcome.kind === "spawn-error")
+        return new Error(`Hook runner failed to spawn: ${outcome.diagnostic}`);
+    return new Error(`Hook runner ended with ${outcome.kind}`);
+}
+async function runPendingCommand(input) {
+    const encoded = Buffer.from(JSON.stringify(input), "utf8").toString("base64url");
+    const outcome = await runProcessToExit({
+        argv: [process.execPath, ...process.execArgv, fileURLToPath(import.meta.url), "--run-hook", encoded],
+        cwd: dirname(fileURLToPath(import.meta.url)),
+    });
+    if (outcome.kind !== "terminal" || outcome.code !== 0)
+        throw runnerFailure(outcome);
+}
+async function runPhase(worktree, administrationDirectory, hooks, phase, retryHooks) {
+    let marker = readMarker(administrationDirectory);
+    if (marker === null) {
+        marker = freshMarker(hooks, phase === "create");
+        writeMarker(administrationDirectory, marker);
+    }
+    let retryFailure = retryHooks && marker[phase].status === "failed";
+    for (;;) {
+        marker = readMarker(administrationDirectory);
+        if (marker === null)
+            throw new Error("worktree hook marker disappeared during execution");
+        const progress = marker[phase];
+        if (progress.status === "ok")
+            return null;
+        if (progress.status === "failed") {
+            if (!retryFailure) {
+                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 }));
+            continue;
+        }
+        if (progress.next === marker.commands[phase].length) {
+            writeMarker(administrationDirectory, withProgress(marker, phase, { status: "ok" }));
+            continue;
+        }
+        await runPendingCommand({ administrationDirectory, worktree, phase, command: progress.next });
+    }
+}
+export function runCreateHooks(worktree, administrationDirectory, hooks, retryHooks) {
+    return runPhase(worktree, administrationDirectory, hooks, "create", retryHooks);
+}
+export function runDestroyHooks(worktree, administrationDirectory, hooks, retryHooks) {
+    return runPhase(worktree, administrationDirectory, hooks, "destroy", retryHooks);
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1] && process.argv[2] === "--run-hook") {
+    const encoded = process.argv[3];
+    if (encoded === undefined)
+        throw new Error("Hook runner input is missing");
+    await executePendingCommand(decodeRunnerInput(encoded));
+}

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

@@ -0,0 +1,17 @@
+import { type ChangeId, type ContractHead, type ContractId, type SnapshotId } from "../core/facts/types.js";
+declare const gitObjectIdBrand: unique symbol;
+export type GitObjectId = string & {
+    readonly [gitObjectIdBrand]: "GitObjectId";
+};
+export declare function contractLocator(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;
+export declare function mintContractHead(value: string): ContractHead;
+export declare function gitObjectIdForSnapshot(value: SnapshotId): GitObjectId;
+export {};

package/build/src/git/identity.js

@@ -0,0 +1,47 @@
+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) {
+    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("/", "-");
+}
+function contractJournalSuffix(contract) {
+    const digest = contractLocator(contract);
+    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))
+        throw new Error(`${label} is not a Git object ID: ${value}`);
+    return value;
+}
+export function mintSnapshotId(value) {
+    return snapshotId(gitObjectId(value, "snapshot"));
+}
+export function mintChangeId(value) {
+    return changeId(gitObjectId(value, "change"));
+}
+export function mintContractHead(value) {
+    return contractHead(gitObjectId(value, "contract head"));
+}
+export function gitObjectIdForSnapshot(value) {
+    return gitObjectId(value, "snapshot");
+}

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

@@ -0,0 +1,49 @@
+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";
+import type { WorkspaceDirtyDelta } 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;
+    changeId: ChangeId;
+}>;
+export type ReviewIntegration = Readonly<{
+    changeId: ChangeId;
+    workspace?: WorkspaceDirtyDelta;
+}>;
+/** 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;
+}>): SnapshotId;
+export declare function planIntegration(repository: GitRepository, input: IntegrationCoordinates, tender: TenderCapture, requireBranchesToBeUpToDate: boolean): Preparation<IntegrationPlan, Readonly<{
+    kind: "target-missing";
+    contractId: ContractId;
+}> | IntegrationPreparationRefusal>;
+/** Prepare the integration-derived review subject from one captured tender. */
+export declare function prepareReviewIntegration(repository: GitRepository, input: IntegrationCoordinates, tender: TenderCapture, workspace?: WorkspaceDirtyDelta): Preparation<ReviewIntegration, Readonly<{
+    kind: "target-missing";
+    contractId: ContractId;
+}> | IntegrationPreparationRefusal>;
+/** 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): string | null;
+export {};

package/build/src/git/integration.js

@@ -0,0 +1,214 @@
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { gitObjectId, gitObjectIdForSnapshot, mintChangeId, mintSnapshotId } from "./identity.js";
+import { GitPlumbingError, readRef, runGit, runGitWithEnvironment, } from "./repository.js";
+const REQUIRED_GIT = "2.38";
+function runAllowingNonzero(repository, args, input) {
+    try {
+        return { stdout: 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 };
+    }
+}
+function stablePatchId(repository, predecessor, tree) {
+    const diff = runGit(repository, ["diff", "--binary", gitObjectIdForSnapshot(predecessor), tree]);
+    const output = runGit(repository, ["patch-id", "--stable"], diff).toString("utf8").trim();
+    const separator = output.indexOf(" ");
+    const identity = output.length === 0
+        ? runGit(repository, ["hash-object", "-t", "blob", "--stdin"], diff).toString("utf8").trim()
+        : separator < 0 ? output : output.slice(0, separator);
+    return mintChangeId(identity);
+}
+/** Materialize the exact integration tree against its observed predecessor. */
+export function materializeIntegrationSnapshot(repository, tree, parent, input) {
+    const commit = 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);
+}
+function isAncestor(repository, ancestor, descendant) {
+    const result = 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",
+    });
+}
+function commonAncestor(repository, left, right) {
+    const result = 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());
+}
+function supportsMergeTree(repository) {
+    return 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);
+}
+function mergedTree(repository, contractId, base, targetHead, tenderTree) {
+    if (!supportsMergeTree(repository)) {
+        return { kind: "refused", refusal: { kind: "integration-unsupported", contractId, requiredGit: REQUIRED_GIT } };
+    }
+    const result = 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 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,
+                changeId: stablePatchId(repository, input.coordinates.start, tender.tree),
+            },
+        };
+    }
+    const observed = 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 (!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 = commonAncestor(repository, tender.head, targetHead);
+        if (base === null) {
+            return {
+                kind: "refused",
+                refusal: {
+                    kind: "integration-failed",
+                    contractId: input.contractId,
+                    reason: "unrelated-histories",
+                    targetHead,
+                },
+            };
+        }
+        const merged = mergedTree(repository, input.contractId, base, targetHead, tender.tree);
+        if (merged.kind === "refused")
+            return merged;
+        tree = merged.data;
+    }
+    return {
+        kind: "prepared",
+        data: {
+            predecessor: targetHead,
+            tree,
+            changeId: stablePatchId(repository, targetHead, tree),
+        },
+    };
+}
+/** Prepare the integration-derived review subject from one captured tender. */
+export function prepareReviewIntegration(repository, input, tender, workspace) {
+    const integration = planIntegration(repository, input, tender, false);
+    return integration.kind === "refused"
+        ? integration
+        : { kind: "prepared", data: { changeId: integration.data.changeId, ...(workspace === undefined ? {} : { workspace }) } };
+}
+function deliverySnapshotAvailability(repository, predecessor, candidate) {
+    const objects = [gitObjectIdForSnapshot(predecessor), gitObjectIdForSnapshot(candidate)];
+    const types = 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";
+}
+/** Read a recorded integration pair's patch, or null when Git no longer has it. */
+export function readDeliveryDiff(repository, predecessor, candidate) {
+    if (deliverySnapshotAvailability(repository, predecessor, candidate) === "unavailable")
+        return null;
+    try {
+        return runGit(repository, [
+            "diff",
+            "--no-ext-diff",
+            "--no-color",
+            gitObjectIdForSnapshot(predecessor),
+            gitObjectIdForSnapshot(candidate),
+        ]).toString("utf8");
+    }
+    catch (error) {
+        if (deliverySnapshotAvailability(repository, predecessor, candidate) === "unavailable")
+            return null;
+        throw error;
+    }
+}