@astrosheep/keiyaku 2.9.13 → 4.0.1

package/build/src/git/repository.js

@@ -0,0 +1,490 @@
+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 = 4;
+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 {
+    stdout;
+    stderr;
+    status;
+    pid;
+    constructor(input) {
+        super(input.message);
+        this.name = "GitPlumbingError";
+        this.stdout = Buffer.from(input.stdout ?? "");
+        this.stderr = Buffer.from(input.stderr);
+        this.status = input.status;
+        this.pid = input.pid ?? null;
+    }
+}
+function worktreesFromPorcelain(output) {
+    const fields = output.toString("utf8").split("\0");
+    const worktrees = [];
+    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");
+        const branchField = record.find((field) => field.startsWith("branch "));
+        const branch = branchField === undefined ? null : branchField.slice("branch ".length);
+        if (branch !== null && !branch.startsWith("refs/"))
+            throw new Error("Git worktree porcelain output has an invalid branch");
+        worktrees.push({ path: resolve(path), branch });
+        record = [];
+    };
+    for (const field of fields) {
+        if (field.length === 0) {
+            finishRecord();
+            continue;
+        }
+        record.push(field);
+    }
+    finishRecord();
+    if (worktrees.length === 0)
+        throw new Error("Git worktree porcelain output has no worktrees");
+    return worktrees;
+}
+export function registeredWorktrees(repository) {
+    return worktreesFromPorcelain(runGit(repository, ["worktree", "list", "--porcelain", "-z"]));
+}
+export function registeredWorktreePaths(repository) { return registeredWorktrees(repository).map((worktree) => worktree.path); }
+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,
+        commonDirectory: effectiveCwd,
+    };
+    let primaryWorktree;
+    let commonDirectory;
+    try {
+        primaryWorktree = registeredWorktreePaths(provisional)[0];
+        commonDirectory = absoluteGitPath(provisional, ["--git-common-dir"], "common Git directory");
+    }
+    catch (error) {
+        if (error instanceof GitPlumbingError && error.status === 128) {
+            throw new NoGitWorldError(effectiveCwd);
+        }
+        throw error;
+    }
+    return { effectiveCwd, primaryWorktree, commonDirectory };
+}
+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 repository.commonDirectory;
+}
+export function worktreeGitDirectory(repository, worktree) {
+    const scoped = { ...repository, effectiveCwd: worktree };
+    return absoluteGitPath(scoped, ["--git-dir"], "worktree Git directory");
+}
+export function worktreeRoot(repository) {
+    return absoluteGitPath(repository, ["--show-toplevel"], "worktree root");
+}
+function commandError(command, error) {
+    const candidate = error;
+    const stderr = candidate.stderr === undefined ? Buffer.alloc(0) : Buffer.from(candidate.stderr);
+    const stdout = candidate.stdout === undefined ? Buffer.alloc(0) : Buffer.from(candidate.stdout);
+    const detail = stderr.length === 0 ? candidate.message ?? "git command failed" : stderr.toString("utf8");
+    return new GitPlumbingError({
+        stdout,
+        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}`);
+    }
+}
+function assertAssertionRef(ref) {
+    if (ref !== "HEAD")
+        assertRef(ref);
+}
+export function readRef(repository, ref) {
+    assertAssertionRef(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, ["show", "-s", "--format=%T", commit]).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;
+}
+export 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;
+}
+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()].find((change) => change !== null)?.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;
+}
+/** Write a tree update from directory entries frozen with the admitted base tree. */
+export function updateGitTreeFromFrozenDirectories(repository, baseTree, directories, changes) {
+    const update = treeUpdate(changes);
+    const representativeOid = baseTree ?? [...changes.values()].find((change) => change !== null)?.oid;
+    if (representativeOid === undefined)
+        throw new Error("cannot write an empty Git tree without an object format");
+    const prepared = prepareTreeUpdate({
+        update,
+        bases: directories,
+        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 }),
+    });
+}
+function refAssertionLine(assertion) {
+    assertAssertionRef(assertion.ref);
+    assertOid(assertion.oid, `expected oid for ${assertion.ref}`);
+    return `${assertion.ref === "HEAD" ? "" : "option no-deref\n"}verify ${assertion.ref} ${assertion.oid}`;
+}
+function refUpdateLine(update, index) {
+    assertRef(update.ref);
+    if (index > 0 && update.ref === GIT_REF)
+        throw new Error(`duplicate ref update: ${update.ref}`);
+    if (index > 0 && 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}`);
+    return `option no-deref\nupdate ${update.ref} ${update.newOid} ${update.expectedOid ?? "0".repeat(update.newOid.length)}`;
+}
+export function updateRefsAtomically(repository, updates, assertions = []) {
+    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",
+        ...assertions.map(refAssertionLine),
+        ...updates.map(refUpdateLine),
+        "prepare",
+        "commit",
+        "",
+    ];
+    try {
+        runGit(repository, ["update-ref", "--stdin"], 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/scratch.d.ts

@@ -0,0 +1,13 @@
+import type { SnapshotId } from "../core/facts/types.js";
+import { type GitRepository } from "./repository.js";
+export type MaterializedScratchCandidate = Readonly<{
+    cwd: string;
+    dispose: () => WorktreeLeak | null;
+}>;
+export type WorktreeLeak = Readonly<{
+    path: string;
+    diagnostic: string;
+}>;
+export declare function orphanedScratchWorktrees(paths: Iterable<string>): readonly string[];
+/** Materialize a disposable candidate worktree and own only its removal. */
+export declare function materializeScratchCandidate(repository: GitRepository, candidate: SnapshotId): MaterializedScratchCandidate;

package/build/src/git/scratch.js

@@ -0,0 +1,66 @@
+import { randomBytes } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gitObjectIdForSnapshot } from "./identity.js";
+import { runGit } from "./repository.js";
+import { currentProcessIdentity, probeProcessIdentity, } from "../runtime/proc/run.js";
+const SCRATCH_PREFIX = "keiyaku-v4-verify-";
+const SCRATCH_ROOT = realpathSync(tmpdir());
+function scratchPath() {
+    const owner = currentProcessIdentity();
+    const identity = Buffer.from(owner.spawnedAt, "utf8").toString("base64url");
+    return join(SCRATCH_ROOT, `${SCRATCH_PREFIX}${owner.pid}-${identity}-${randomBytes(12).toString("hex")}`);
+}
+function scratchOwner(path) {
+    const prefix = join(SCRATCH_ROOT, SCRATCH_PREFIX);
+    if (!path.startsWith(prefix))
+        return null;
+    const suffix = path.slice(prefix.length);
+    const match = /^([1-9][0-9]*)-([A-Za-z0-9_-]+)-([0-9a-f]{24})$/.exec(suffix);
+    if (match === null)
+        return null;
+    const pid = Number(match[1]);
+    if (!Number.isSafeInteger(pid))
+        return null;
+    let spawnedAt;
+    try {
+        spawnedAt = Buffer.from(match[2], "base64url").toString("utf8");
+    }
+    catch {
+        return null;
+    }
+    return spawnedAt.length === 0 ? null : { pid, spawnedAt };
+}
+export function orphanedScratchWorktrees(paths) {
+    const orphaned = [];
+    for (const path of paths) {
+        const owner = scratchOwner(path);
+        if (owner === null)
+            continue;
+        const state = probeProcessIdentity(owner);
+        if (state.kind === "gone" || state.kind === "replaced")
+            orphaned.push(path);
+    }
+    return orphaned;
+}
+/** Materialize a disposable candidate worktree and own only its removal. */
+export function materializeScratchCandidate(repository, candidate) {
+    const cwd = scratchPath();
+    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),
+                };
+            }
+        },
+    };
+}

package/build/src/git/target-placement.d.ts

@@ -0,0 +1,56 @@
+import { type HeldSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
+import type { ContractId, ContractState, SnapshotId } from "../core/facts/types.js";
+import type { RefOperation } from "../core/facts/offer.js";
+import { type GitRepository } from "./repository.js";
+export type WorkspaceNotOnTargetRefusal = Readonly<{
+    kind: "workspace-not-on-target";
+    contractId: ContractId;
+    target: string;
+    branch: string | null;
+}>;
+export type CheckoutNotFollowableRefusal = Readonly<{
+    kind: "checkout-not-followable";
+    contractId: ContractId;
+    target: string;
+    path: string;
+    reason: "staged" | "conflict" | "untracked";
+    paths: readonly string[];
+}>;
+export type TargetPlacementRefusal = CheckoutNotFollowableRefusal | WorkspaceNotOnTargetRefusal;
+export type TargetCheckoutEffect = Readonly<{
+    kind: "target-checkout";
+    path: string;
+    target: string;
+    action: "followed" | "recovered";
+}>;
+export type TargetCheckoutLag = Readonly<{
+    kind: "target-checkout-retained";
+    path: string;
+    target: string;
+    diagnostic: string;
+}>;
+export type TargetPlacementPhysicalResult = Readonly<{
+    effects: readonly TargetCheckoutEffect[];
+    lag: readonly TargetCheckoutLag[];
+}>;
+type FollowArm = Readonly<{
+    kind: "ordinary" | "here";
+    path: string;
+}>;
+export type PreparedTargetPlacement = Readonly<{
+    target: RefOperation;
+    arms: readonly FollowArm[];
+}>;
+export type TargetPlacementPreparation = Readonly<{
+    kind: "prepared";
+    placement: PreparedTargetPlacement;
+}> | Readonly<{
+    kind: "refused";
+    refusal: TargetPlacementRefusal;
+}>;
+export declare function observeTargetHead(repository: GitRepository, target: string): SnapshotId | null;
+export declare function acquireTargetPlacementFence(repository: GitRepository, target: string): Promise<HeldSqliteTransactionLock>;
+export declare function prepareTargetPlacement(repository: GitRepository, state: ContractState, target: RefOperation): TargetPlacementPreparation;
+export declare function followTargetPlacement(repository: GitRepository, prepared: PreparedTargetPlacement): TargetPlacementPhysicalResult;
+export declare function recoverTargetPlacement(repository: GitRepository, state: ContractState): TargetPlacementPhysicalResult;
+export {};