@astrosheep/keiyaku 2.9.12 → 4.0.0

package/build/src/git/repository.js

@@ -0,0 +1,456 @@
+import { execFileSync } from "node:child_process";
+import { isAbsolute, resolve } from "node:path";
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { gitObjectId } from "./identity.js";
+import { parseTreeObject, prepareTreeUpdate, treeUpdate, validPath, } from "./tree.js";
+export const GIT_REF = "refs/heads/keiyaku-state";
+export const DELIVERY_REF_NAMESPACE = "refs/heads/keiyaku-delivery";
+export const CANDIDATE_PIN_REF_NAMESPACE = "refs/heads/keiyaku-candidate";
+export const GIT_FORMAT_PATH = "meta/format.json";
+const CURRENT_FORMAT_VERSION = 3;
+export const GIT_FORMAT_BYTES = `{"version":${CURRENT_FORMAT_VERSION}}\n`;
+export function isKeiyakuOwnedRef(ref) {
+    return ref === GIT_REF
+        || ref === DELIVERY_REF_NAMESPACE
+        || ref.startsWith(`${DELIVERY_REF_NAMESPACE}/`)
+        || ref === CANDIDATE_PIN_REF_NAMESPACE
+        || ref.startsWith(`${CANDIDATE_PIN_REF_NAMESPACE}/`);
+}
+export class NoGitWorldError extends Error {
+    path;
+    constructor(path) {
+        super(`no Git world at: ${path}`);
+        this.name = "NoGitWorldError";
+        this.path = path;
+    }
+}
+export class GitPlumbingError extends Error {
+    stderr;
+    status;
+    pid;
+    constructor(input) {
+        super(input.message);
+        this.name = "GitPlumbingError";
+        this.stderr = Buffer.from(input.stderr);
+        this.status = input.status;
+        this.pid = input.pid ?? null;
+    }
+}
+function worktreePathsFromPorcelain(output) {
+    const fields = output.toString("utf8").split("\0");
+    const paths = [];
+    let record = [];
+    const finishRecord = () => {
+        if (record.length === 0)
+            return;
+        const worktree = record[0];
+        if (worktree === undefined || !worktree.startsWith("worktree ")) {
+            throw new Error("Git worktree porcelain output is missing a worktree path");
+        }
+        const path = worktree.slice("worktree ".length);
+        if (path.length === 0)
+            throw new Error("Git worktree porcelain output has an empty worktree path");
+        paths.push(resolve(path));
+        record = [];
+    };
+    for (const field of fields) {
+        if (field.length === 0) {
+            finishRecord();
+            continue;
+        }
+        record.push(field);
+    }
+    finishRecord();
+    if (paths.length === 0)
+        throw new Error("Git worktree porcelain output has no worktrees");
+    return paths;
+}
+export function registeredWorktreePaths(repository) {
+    return worktreePathsFromPorcelain(runGit(repository, ["worktree", "list", "--porcelain", "-z"]));
+}
+export function repositoryAt(cwd) {
+    if (typeof cwd !== "string" || cwd.length === 0) {
+        throw new Error("repository path must be a nonempty string");
+    }
+    const effectiveCwd = resolve(cwd);
+    const provisional = { effectiveCwd, primaryWorktree: effectiveCwd };
+    let primaryWorktree;
+    try {
+        primaryWorktree = registeredWorktreePaths(provisional)[0];
+    }
+    catch (error) {
+        if (error instanceof GitPlumbingError && error.status === 128) {
+            throw new NoGitWorldError(effectiveCwd);
+        }
+        throw error;
+    }
+    return { effectiveCwd, primaryWorktree };
+}
+function absoluteGitPath(repository, args, label) {
+    const value = runGit(repository, ["rev-parse", "--path-format=absolute", ...args]).toString("utf8").trim();
+    if (value.length === 0)
+        throw new Error(`${label} is empty`);
+    return resolve(isAbsolute(value) ? value : resolve(repository.effectiveCwd, value));
+}
+export function commonGitDirectory(repository) {
+    return absoluteGitPath(repository, ["--git-common-dir"], "common Git directory");
+}
+export function worktreeGitDirectory(repository, worktree) {
+    const scoped = { ...repository, effectiveCwd: worktree };
+    return absoluteGitPath(scoped, ["--git-dir"], "worktree Git directory");
+}
+function commandError(command, error) {
+    const candidate = error;
+    const stderr = candidate.stderr === undefined ? Buffer.alloc(0) : Buffer.from(candidate.stderr);
+    const detail = stderr.length === 0 ? candidate.message ?? "git command failed" : stderr.toString("utf8");
+    return new GitPlumbingError({
+        stderr,
+        status: candidate.status ?? null,
+        message: `${command.join(" ")}: ${detail}`,
+        pid: candidate.pid ?? null,
+    });
+}
+export function runGit(repository, args, input) {
+    try {
+        const output = execFileSync("git", [...args], {
+            cwd: repository.effectiveCwd,
+            input,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return Buffer.isBuffer(output) ? output : Buffer.from(output);
+    }
+    catch (error) {
+        throw commandError(args, error);
+    }
+}
+export function runGitWithEnvironment(repository, args, input, environment) {
+    try {
+        const output = execFileSync("git", [...args], {
+            cwd: repository.effectiveCwd,
+            input,
+            env: { ...process.env, ...environment },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return Buffer.isBuffer(output) ? output : Buffer.from(output);
+    }
+    catch (error) {
+        throw commandError(args, error);
+    }
+}
+function assertOid(oid, label) {
+    gitObjectId(oid, label);
+}
+function assertRef(ref) {
+    if (!ref.startsWith("refs/") || /[\s\0]/.test(ref) || ref.endsWith("/") || ref.includes("..")) {
+        throw new Error(`invalid Git ref: ${ref}`);
+    }
+}
+export function readRef(repository, ref) {
+    assertRef(ref);
+    try {
+        const oid = runGit(repository, ["rev-parse", "--verify", "--quiet", ref]).toString("utf8").trim();
+        if (oid.length === 0)
+            return null;
+        assertOid(oid, `ref ${ref}`);
+        return oid;
+    }
+    catch (error) {
+        if (error instanceof GitPlumbingError && error.status === 1)
+            return null;
+        throw error;
+    }
+}
+function readTreeForCommit(repository, commit) {
+    assertOid(commit, "Git commit");
+    const tree = runGit(repository, ["rev-parse", "--verify", `${commit}^{tree}`]).toString("utf8").trim();
+    assertOid(tree, "Git tree");
+    return tree;
+}
+function parseTreeEntries(output) {
+    const entries = new Map();
+    for (const record of output.toString("utf8").split("\0")) {
+        if (record.length === 0)
+            continue;
+        const separator = record.indexOf("\t");
+        if (separator < 0)
+            throw new GitPlumbingError({ stderr: record, status: null, message: `malformed ls-tree record: ${record}` });
+        const [mode, type, oid] = record.slice(0, separator).split(" ");
+        const path = record.slice(separator + 1);
+        if (mode === undefined || type === undefined || oid === undefined || path.length === 0) {
+            throw new GitPlumbingError({ stderr: record, status: null, message: `malformed ls-tree record: ${record}` });
+        }
+        assertOid(oid, `tree entry ${path}`);
+        entries.set(path, { mode, type, oid });
+    }
+    return entries;
+}
+function readTreeEntries(repository, tree) {
+    assertOid(tree, "tree");
+    const output = runGit(repository, ["ls-tree", "-r", "-z", "--full-tree", tree]);
+    return parseTreeEntries(output);
+}
+export function readGit(repository) {
+    const commit = readRef(repository, GIT_REF);
+    if (commit === null) {
+        return { commit: null, tree: null, paths: new Map() };
+    }
+    const tree = readTreeForCommit(repository, commit);
+    const paths = readTreeEntries(repository, tree);
+    validateGitFormat(repository, paths);
+    return { commit, tree, paths };
+}
+/** Read only the requested private Git paths from one immutable Git tree. */
+export function readGitPaths(repository, requestedPaths) {
+    for (const path of requestedPaths)
+        validPath(path);
+    const commit = readRef(repository, GIT_REF);
+    if (commit === null)
+        return { commit: null, tree: null, paths: new Map() };
+    const tree = readTreeForCommit(repository, commit);
+    const paths = parseTreeEntries(runGit(repository, [
+        "ls-tree",
+        "-z",
+        "--full-tree",
+        tree,
+        "--",
+        GIT_FORMAT_PATH,
+        ...requestedPaths,
+    ]));
+    validateGitFormat(repository, paths);
+    return { commit, tree, paths };
+}
+/** Add paths from the same immutable Git tree without rereading its ref. */
+export function extendGitPaths(repository, snapshot, requestedPaths) {
+    for (const path of requestedPaths)
+        validPath(path);
+    if (snapshot.tree === null || requestedPaths.length === 0)
+        return snapshot;
+    const additions = parseTreeEntries(runGit(repository, [
+        "ls-tree",
+        "-z",
+        "--full-tree",
+        snapshot.tree,
+        "--",
+        ...requestedPaths,
+    ]));
+    return { ...snapshot, paths: new Map([...snapshot.paths, ...additions]) };
+}
+/** Expand a targeted immutable snapshot to its complete already-pinned tree. */
+export function expandGitSnapshot(repository, snapshot) {
+    if (snapshot.tree === null)
+        return snapshot;
+    return { ...snapshot, paths: readTreeEntries(repository, snapshot.tree) };
+}
+export function writeBlob(repository, bytes) {
+    const oid = runGit(repository, ["hash-object", "-w", "--stdin"], bytes).toString("utf8").trim();
+    assertOid(oid, "written blob");
+    return oid;
+}
+export function readBlob(repository, oid) {
+    assertOid(oid, "blob");
+    return runGit(repository, ["cat-file", "blob", oid]);
+}
+function malformedBatchOutput(detail) {
+    throw new GitPlumbingError({
+        stderr: Buffer.alloc(0),
+        status: null,
+        message: `malformed cat-file --batch output: ${detail}`,
+    });
+}
+function readObjects(repository, oids) {
+    const unique = [...new Set(oids)];
+    for (const oid of unique)
+        assertOid(oid, "Git object");
+    if (unique.length === 0)
+        return new Map();
+    const output = runGit(repository, ["cat-file", "--batch"], `${unique.join("\n")}\n`);
+    const objects = new Map();
+    let offset = 0;
+    for (const oid of unique) {
+        const headerEnd = output.indexOf(0x0a, offset);
+        if (headerEnd < 0)
+            malformedBatchOutput(`missing header for ${oid}`);
+        const fields = output.subarray(offset, headerEnd).toString("ascii").split(" ");
+        offset = headerEnd + 1;
+        if (fields.length === 2 && fields[0] === oid && fields[1] === "missing") {
+            throw new GitPlumbingError({
+                stderr: `missing Git object: ${oid}`,
+                status: 1,
+                message: `cat-file --batch: missing Git object ${oid}`,
+            });
+        }
+        if (fields.length !== 3 || fields[0] !== oid || fields[1] === undefined || fields[2] === undefined) {
+            malformedBatchOutput(`unexpected header for ${oid}`);
+        }
+        if (!/^(0|[1-9][0-9]*)$/.test(fields[2]))
+            malformedBatchOutput(`invalid size for ${oid}`);
+        const size = Number(fields[2]);
+        if (!Number.isSafeInteger(size) || size < 0 || size > output.length - offset) {
+            malformedBatchOutput(`invalid content length for ${oid}`);
+        }
+        const bytes = output.subarray(offset, offset + size);
+        offset += size;
+        if (output[offset] !== 0x0a)
+            malformedBatchOutput(`missing content delimiter for ${oid}`);
+        offset += 1;
+        objects.set(oid, { type: fields[1], bytes });
+    }
+    if (offset !== output.length)
+        malformedBatchOutput("trailing bytes");
+    return objects;
+}
+/** Read immutable Git objects through one structured, length-delimited batch. */
+export function readBlobs(repository, oids) {
+    const blobs = new Map();
+    for (const [oid, object] of readObjects(repository, oids)) {
+        if (object.type !== "blob")
+            malformedBatchOutput(`expected blob for ${oid}, found ${object.type}`);
+        blobs.set(oid, object.bytes);
+    }
+    return blobs;
+}
+function validateGitFormat(repository, paths) {
+    const format = paths.get(GIT_FORMAT_PATH);
+    if (format === undefined)
+        throw new AuthorityCorruptionError(`Git is missing ${GIT_FORMAT_PATH}`);
+    if (format.type !== "blob")
+        throw new AuthorityCorruptionError(`Git format is not a blob: ${GIT_FORMAT_PATH}`);
+    const bytes = readBlob(repository, format.oid);
+    if (bytes.toString("utf8") !== GIT_FORMAT_BYTES) {
+        throw new AuthorityCorruptionError(`Git format is not current: ${GIT_FORMAT_PATH}`);
+    }
+}
+function baseTreeEntries(repository, baseTree, changedPaths, nodePaths) {
+    const byPath = new Map();
+    if (baseTree === null)
+        return byPath;
+    const ancestry = parseTreeEntries(runGit(repository, [
+        "ls-tree",
+        "-z",
+        "-t",
+        "-r",
+        "--full-tree",
+        baseTree,
+        "--",
+        ...changedPaths.map((path) => `:(literal)${path}`),
+    ]));
+    const treeByPath = new Map([["", baseTree]]);
+    for (const path of nodePaths) {
+        if (path.length === 0)
+            continue;
+        const entry = ancestry.get(path);
+        if (entry === undefined)
+            continue;
+        if (entry.type !== "tree")
+            throw new Error(`Git path is both file and directory: ${path}`);
+        treeByPath.set(path, entry.oid);
+    }
+    const objects = readObjects(repository, [...treeByPath.values()]);
+    const oidBytes = baseTree.length / 2;
+    for (const [path, oid] of treeByPath) {
+        const object = objects.get(oid);
+        if (object === undefined || object.type !== "tree") {
+            throw new GitPlumbingError({ stderr: oid, status: null, message: `Git tree is not a tree: ${path || "/"}` });
+        }
+        byPath.set(path, parseTreeObject(object.bytes, oidBytes));
+    }
+    return byPath;
+}
+function writePreparedTrees(repository, prepared) {
+    const output = runGit(repository, ["mktree", "--batch"], prepared.map(({ records }) => `${records}\n`).join(""));
+    const written = output.toString("ascii").trimEnd().split("\n");
+    if (written.length !== prepared.length) {
+        throw new GitPlumbingError({ stderr: output, status: null, message: "malformed mktree --batch output" });
+    }
+    for (let index = 0; index < prepared.length; index += 1) {
+        const expected = prepared[index].oid;
+        const actual = written[index];
+        assertOid(actual, "written tree");
+        if (actual !== expected) {
+            throw new GitPlumbingError({ stderr: output, status: null, message: `mktree wrote unexpected tree: ${actual}` });
+        }
+    }
+}
+/** Copy only the changed paths' tree ancestors, preserving untouched subtrees by object ID. */
+export function updateGitTree(repository, baseTree, changes) {
+    const update = treeUpdate(changes);
+    const bases = baseTreeEntries(repository, baseTree, [...changes.keys()], update.nodePaths);
+    const representativeOid = baseTree ?? changes.values().next().value?.oid;
+    if (representativeOid === undefined)
+        throw new Error("cannot write an empty Git tree without an object format");
+    const prepared = prepareTreeUpdate({ update, bases, oidBytes: representativeOid.length / 2 });
+    writePreparedTrees(repository, prepared.trees);
+    return prepared.root;
+}
+function writeCommitObject(input) {
+    const { repository, tree, parents, message, actor, email, at } = input;
+    assertOid(tree, "commit tree");
+    for (const parent of parents)
+        assertOid(parent, "commit parent");
+    const args = ["commit-tree", tree];
+    for (const parent of parents)
+        args.push("-p", parent);
+    const commit = runGitWithEnvironment(repository, args, `${message}\n`, {
+        GIT_AUTHOR_NAME: actor,
+        GIT_AUTHOR_EMAIL: email,
+        GIT_COMMITTER_NAME: actor,
+        GIT_COMMITTER_EMAIL: email,
+        ...(at === undefined ? {} : { GIT_AUTHOR_DATE: at, GIT_COMMITTER_DATE: at }),
+    })
+        .toString("utf8")
+        .trim();
+    assertOid(commit, "written Git commit");
+    return commit;
+}
+export function writeCommit(input) {
+    return writeCommitObject({
+        repository: input.repository,
+        tree: input.tree,
+        parents: input.parent === null ? [] : [input.parent],
+        message: input.message ?? "keiyaku facts transaction",
+        actor: input.actor ?? "Keiyaku Git",
+        email: "keiyaku@localhost",
+        ...(input.at === undefined ? {} : { at: input.at }),
+    });
+}
+export function updateRefsAtomically(repository, updates) {
+    if (updates.length === 0)
+        throw new Error("an atomic ref transaction needs a Git update");
+    if (updates.length > 2)
+        throw new Error("an atomic ref transaction accepts at most one target ref update");
+    const git = updates[0];
+    if (git === undefined || git.ref !== GIT_REF) {
+        throw new Error(`the first atomic update must be the Git ref: ${GIT_REF}`);
+    }
+    const lines = ["start"];
+    for (const [index, update] of updates.entries()) {
+        assertRef(update.ref);
+        if (index > 0 && update.ref === GIT_REF) {
+            throw new Error(`duplicate ref update: ${update.ref}`);
+        }
+        if (index > 0 && (update.newOid === null || update.expectedOid === null)) {
+            throw new Error("target ref updates require non-null OIDs");
+        }
+        assertOid(update.newOid, `new oid for ${update.ref}`);
+        if (update.expectedOid !== null)
+            assertOid(update.expectedOid, `expected oid for ${update.ref}`);
+        const expectedOid = update.expectedOid ?? "0".repeat(update.newOid.length);
+        lines.push(`update ${update.ref} ${update.newOid} ${expectedOid}`);
+    }
+    lines.push("prepare", "commit", "");
+    try {
+        runGit(repository, ["update-ref", "--stdin", "--no-deref"], lines.join("\n"));
+        return { kind: "published" };
+    }
+    catch (error) {
+        if (!(error instanceof GitPlumbingError))
+            throw error;
+        if (error.status !== null && error.status !== 0) {
+            return { kind: "non-published", error };
+        }
+        if (error.pid !== null && error.pid > 0 && error.status === null) {
+            return { kind: "unknown" };
+        }
+        throw error;
+    }
+}

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

@@ -0,0 +1,34 @@
+export type TreeEntry = Readonly<{
+    mode: string;
+    type: string;
+    oid: string;
+}>;
+export type TreeChange = Readonly<{
+    oid: string;
+    mode?: string;
+    type?: string;
+}>;
+type MutableTreeNode = Readonly<{
+    files: Map<string, TreeChange>;
+    directories: Map<string, MutableTreeNode>;
+}>;
+type TreeUpdate = Readonly<{
+    root: MutableTreeNode;
+    nodePaths: readonly string[];
+}>;
+export type PreparedTree = Readonly<{
+    oid: string;
+    records: string;
+}>;
+export declare function validPath(path: string): void;
+export declare function treeUpdate(changes: ReadonlyMap<string, TreeChange>): TreeUpdate;
+export declare function parseTreeObject(bytes: Buffer, oidBytes: number): Map<string, TreeEntry>;
+export declare function prepareTreeUpdate(input: Readonly<{
+    update: TreeUpdate;
+    bases: ReadonlyMap<string, Map<string, TreeEntry>>;
+    oidBytes: number;
+}>): Readonly<{
+    root: string;
+    trees: readonly PreparedTree[];
+}>;
+export {};

package/build/src/git/tree.js

@@ -0,0 +1,112 @@
+import { createHash } from "node:crypto";
+import { gitObjectId } from "./identity.js";
+export function validPath(path) {
+    if (path.length === 0 || path.startsWith("/") || path.endsWith("/") || path.includes("\0")
+        || path.split("/").some((part) => part.length === 0 || part === "." || part === ".."))
+        throw new Error(`invalid Git path: ${path}`);
+}
+function addEntry(root, path, change) {
+    validPath(path);
+    const parts = path.split("/");
+    let node = root;
+    for (const part of parts.slice(0, -1)) {
+        if (node.files.has(part))
+            throw new Error(`Git path is both file and directory: ${path}`);
+        let child = node.directories.get(part);
+        if (child === undefined) {
+            child = { files: new Map(), directories: new Map() };
+            node.directories.set(part, child);
+        }
+        node = child;
+    }
+    const name = parts.at(-1);
+    if (name === undefined || node.directories.has(name)) {
+        throw new Error(`Git path is both file and directory: ${path}`);
+    }
+    node.files.set(name, change);
+}
+function nodePaths(node, path = "", result = []) {
+    result.push(path);
+    for (const [name, child] of node.directories) {
+        nodePaths(child, path.length === 0 ? name : `${path}/${name}`, result);
+    }
+    return result;
+}
+export function treeUpdate(changes) {
+    const root = { files: new Map(), directories: new Map() };
+    for (const [path, change] of changes)
+        addEntry(root, path, change);
+    return { root, nodePaths: nodePaths(root) };
+}
+function entryType(mode) {
+    return mode === "040000" || mode === "40000" ? "tree" : mode === "160000" ? "commit" : "blob";
+}
+export function parseTreeObject(bytes, oidBytes) {
+    const entries = new Map();
+    let offset = 0;
+    while (offset < bytes.length) {
+        const modeEnd = bytes.indexOf(0x20, offset);
+        const nameEnd = modeEnd < 0 ? -1 : bytes.indexOf(0, modeEnd + 1);
+        if (modeEnd < 0 || nameEnd < 0 || nameEnd + 1 + oidBytes > bytes.length) {
+            throw new Error("malformed Git tree object");
+        }
+        const rawMode = bytes.subarray(offset, modeEnd).toString("ascii");
+        const mode = rawMode === "40000" ? "040000" : rawMode;
+        const name = bytes.subarray(modeEnd + 1, nameEnd).toString("utf8");
+        if (name.length === 0 || entries.has(name))
+            throw new Error("malformed Git tree object");
+        const oid = bytes.subarray(nameEnd + 1, nameEnd + 1 + oidBytes).toString("hex");
+        gitObjectId(oid, `tree entry ${name}`);
+        entries.set(name, { mode, type: entryType(mode), oid });
+        offset = nameEnd + 1 + oidBytes;
+    }
+    return entries;
+}
+function sortName(name, type) {
+    return Buffer.concat([Buffer.from(name), Buffer.from([type === "tree" ? 0x2f : 0])]);
+}
+function objectId(entries, oidBytes) {
+    const sorted = [...entries].sort((left, right) => sortName(left[0], left[1].type).compare(sortName(right[0], right[1].type)));
+    const parts = sorted.flatMap(([name, entry]) => [
+        Buffer.from(`${entry.mode === "040000" ? "40000" : entry.mode} ${name}\0`),
+        Buffer.from(entry.oid, "hex"),
+    ]);
+    const bytes = Buffer.concat(parts);
+    const algorithm = oidBytes === 20 ? "sha1" : oidBytes === 32 ? "sha256" : null;
+    if (algorithm === null)
+        throw new Error(`unsupported Git object ID width: ${oidBytes * 2}`);
+    return createHash(algorithm).update(`tree ${bytes.length}\0`).update(bytes).digest("hex");
+}
+function record(name, change) {
+    gitObjectId(change.oid, `tree entry ${name}`);
+    const mode = change.mode ?? "100644";
+    const type = change.type ?? (mode === "160000" ? "commit" : "blob");
+    return `${mode} ${type} ${change.oid}\t${name}\n`;
+}
+function prepareNode(node, path, bases, oidBytes, prepared) {
+    const entries = new Map(bases.get(path) ?? []);
+    for (const [name, change] of node.files) {
+        entries.set(name, {
+            oid: change.oid,
+            mode: change.mode ?? "100644",
+            type: change.type ?? (change.mode === "160000" ? "commit" : "blob"),
+        });
+    }
+    for (const [name, child] of node.directories) {
+        const prior = entries.get(name);
+        if (prior !== undefined && prior.type !== "tree") {
+            throw new Error(`Git path is both file and directory: ${name}`);
+        }
+        const childPath = path.length === 0 ? name : `${path}/${name}`;
+        const oid = prepareNode(child, childPath, bases, oidBytes, prepared);
+        entries.set(name, { mode: "040000", type: "tree", oid });
+    }
+    const oid = objectId(entries, oidBytes);
+    prepared.push({ oid, records: [...entries].map(([name, entry]) => record(name, entry)).join("") });
+    return oid;
+}
+export function prepareTreeUpdate(input) {
+    const trees = [];
+    const root = prepareNode(input.update.root, "", input.bases, input.oidBytes, trees);
+    return { root, trees };
+}

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

@@ -0,0 +1,14 @@
+import type { SnapshotId } from "../core/facts/types.js";
+import { type GitRepository } from "./repository.js";
+type MaterializedVerificationCandidate = Readonly<{
+    cwd: string;
+    dispose: () => WorktreeLeak | null;
+}>;
+export type WorktreeLeak = Readonly<{
+    path: string;
+    diagnostic: string;
+}>;
+/** Materialize a temporary candidate worktree for verification and own its cleanup. */
+export declare function materializeVerificationCandidate(repository: GitRepository, candidate: SnapshotId): MaterializedVerificationCandidate;
+export declare function readDeliveryDiff(repository: GitRepository, predecessor: SnapshotId, candidate: SnapshotId): string | null;
+export {};

package/build/src/git/verification.js

@@ -0,0 +1,56 @@
+import { randomBytes } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { gitObjectIdForSnapshot } from "./identity.js";
+import { runGit } from "./repository.js";
+/** Materialize a temporary candidate worktree for verification and own its cleanup. */
+export function materializeVerificationCandidate(repository, candidate) {
+    const cwd = join(tmpdir(), `keiyaku-v4-verify-${randomBytes(12).toString("hex")}`);
+    runGit(repository, ["worktree", "add", "--detach", cwd, gitObjectIdForSnapshot(candidate)]);
+    return {
+        cwd,
+        dispose: () => {
+            try {
+                runGit(repository, ["worktree", "remove", "--force", cwd]);
+                return null;
+            }
+            catch (error) {
+                return {
+                    path: cwd,
+                    diagnostic: error instanceof Error ? error.message : String(error),
+                };
+            }
+        },
+    };
+}
+/** Resolve both pinned delivery objects through one structured Git batch. */
+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";
+}
+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) {
+        // A pruning race after the probes is still Git absence, not a Git error for callers.
+        if (deliverySnapshotAvailability(repository, predecessor, candidate) === "unavailable")
+            return null;
+        throw error;
+    }
+}

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

@@ -0,0 +1,9 @@
+export type IdentityFamily = "aku" | "kei" | "task" | "resp";
+export declare function identityCoordinate(input: Readonly<{
+    family: IdentityFamily;
+    segments: readonly string[];
+}>): string;
+export declare function identitySegments(input: Readonly<{
+    family: IdentityFamily;
+    value: string;
+}>): readonly string[];