@astrosheep/keiyaku 2.9.13 → 4.0.1

package/build/src/git/reconcile.js

@@ -0,0 +1,376 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { acquireSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { CANDIDATE_PIN_REF_NAMESPACE, commonGitDirectory, DELIVERY_REF_NAMESPACE, GitPlumbingError, isKeiyakuOwnedRef, readRef, registeredWorktreePaths, runGit, worktreeGitDirectory, } from "./repository.js";
+import { contractLocator, contractPhysicalName, gitObjectIdForSnapshot, mintSnapshotId, } from "./identity.js";
+import { observeContractAt } from "./observe.js";
+import { acquireTargetPlacementFence, recoverTargetPlacement, } from "./target-placement.js";
+import { runCreateHooks, runDestroyHooks, } from "./hooks.js";
+import { deliveryWorktreePath } from "./workspace.js";
+import { orphanedScratchWorktrees } from "./scratch.js";
+import { terminalSealExpectations as decodeTerminalSealExpectations, terminalSealSnapshots, unsealedBytes, } from "./terminal-seal.js";
+function deliveryRefFor(contract) { return `${DELIVERY_REF_NAMESPACE}/${contractPhysicalName(contract)}`; }
+function candidatePinRefFor(contract) { return `${CANDIDATE_PIN_REF_NAMESPACE}/${contractPhysicalName(contract)}`; }
+function updateRef(repository, ref, desired) {
+    const before = readRef(repository, ref);
+    if (before === desired)
+        return { kind: "ref", name: ref, action: "unchanged", before, after: desired };
+    runGit(repository, ["update-ref", "--no-deref", ref, gitObjectIdForSnapshot(desired), before ?? "0".repeat(desired.length)]);
+    return { kind: "ref", name: ref, action: before === null ? "created" : "updated", before, after: desired };
+}
+function removeRef(repository, ref) {
+    const before = readRef(repository, ref);
+    if (before === null)
+        return { kind: "ref", name: ref, action: "unchanged", before: null, after: null };
+    runGit(repository, ["update-ref", "--no-deref", "-d", ref, before]);
+    return { kind: "ref", name: ref, action: "removed", before, after: null };
+}
+function removeRefWithCustody(repository, ref, custodian, expectedCustodian) {
+    const before = readRef(repository, ref);
+    if (before === null)
+        return { kind: "ref", name: ref, action: "unchanged", before: null, after: null };
+    if (readRef(repository, custodian) !== expectedCustodian) {
+        return { kind: "ref", name: ref, action: "unchanged", before, after: before };
+    }
+    runGit(repository, ["update-ref", "--stdin", "--no-deref"], [
+        "start",
+        `verify ${custodian} ${gitObjectIdForSnapshot(expectedCustodian)}`,
+        `delete ${ref} ${before}`,
+        "prepare",
+        "commit",
+        "",
+    ].join("\n"));
+    return { kind: "ref", name: ref, action: "removed", before, after: null };
+}
+function acquireWorktreeTopology(repository) {
+    return { paths: new Set(registeredWorktreePaths(repository)) };
+}
+function fromPrimaryWorktree(repository) {
+    return { ...repository, effectiveCwd: repository.primaryWorktree };
+}
+function diagnostic(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function complete(effects = [], lag = []) {
+    return { effects, lag };
+}
+function failed(stage, error, effects = [], lag = []) {
+    if (error instanceof AuthorityCorruptionError || error instanceof TypeError)
+        throw error;
+    return { effects, lag: [...lag, { kind: "reconcile-failed", stage, diagnostic: diagnostic(error) }] };
+}
+function reconcileLockPath(repository, contract) {
+    const locator = contractLocator(contract);
+    return join(commonGitDirectory(repository), "keiyaku", "locks", "reconcile", locator.slice(0, 2), `${locator.slice(2)}.sqlite`);
+}
+function worktree(repository, topology, path, desired) {
+    const registered = topology.paths.has(path);
+    if (registered && existsSync(path))
+        return { kind: "worktree", path, action: "unchanged" };
+    if (registered) {
+        runGit(repository, ["worktree", "remove", path]);
+        topology.paths.delete(path);
+    }
+    if (existsSync(path))
+        throw new Error(`delivery worktree path is occupied: ${path}`);
+    mkdirSync(dirname(path), { recursive: true });
+    runGit(repository, ["worktree", "add", "--detach", path, gitObjectIdForSnapshot(desired)]);
+    topology.paths.add(path);
+    return { kind: "worktree", path, action: "created" };
+}
+function removeWorktree(repository, topology, path, force = false) {
+    const registered = topology.paths.has(path);
+    if (!registered)
+        return { effect: { kind: "worktree", path, action: "unchanged" }, retained: false };
+    if (!existsSync(path)) {
+        runGit(repository, ["worktree", "remove", path]);
+        topology.paths.delete(path);
+        return { effect: { kind: "worktree", path, action: "removed" }, retained: false };
+    }
+    try {
+        runGit(repository, ["worktree", "remove", ...(force ? ["--force"] : []), path]);
+    }
+    catch {
+        return { effect: { kind: "worktree", path, action: "unchanged" }, retained: true };
+    }
+    topology.paths.delete(path);
+    return { effect: { kind: "worktree", path, action: "removed" }, retained: false };
+}
+function removeOrphanedScratch(repository, topology, effects, lag) {
+    for (const path of orphanedScratchWorktrees(topology.paths)) {
+        const removal = removeWorktree(repository, topology, path, true);
+        effects.push(removal.effect);
+        if (removal.retained)
+            lag.push({ kind: "worktree-retained", path });
+    }
+}
+function refRows(repository) {
+    const output = runGit(repository, [
+        "for-each-ref",
+        "--format=%(refname)%00%(objectname)",
+    ]).toString("utf8");
+    if (output.length === 0)
+        return [];
+    return output.trimEnd().split("\n").map((row) => {
+        const [ref, oid, extra] = row.split("\0");
+        if (ref === undefined || oid === undefined || extra !== undefined)
+            throw new Error("Git ref row is malformed");
+        return { ref, oid };
+    });
+}
+function snapshotCustodian(repository, snapshot) {
+    for (const row of refRows(repository)) {
+        if (isKeiyakuOwnedRef(row.ref))
+            continue;
+        try {
+            runGit(repository, ["merge-base", "--is-ancestor", gitObjectIdForSnapshot(snapshot), row.oid]);
+            return { ref: row.ref, oid: mintSnapshotId(row.oid) };
+        }
+        catch (error) {
+            if (error instanceof GitPlumbingError && error.status === 1)
+                continue;
+            throw error;
+        }
+    }
+    return null;
+}
+async function reconcileTargetCheckouts(repository, state) {
+    if (state.terminal?.kind !== "claimed" || state.coordinates.target === undefined || state.delivery === null) {
+        return complete();
+    }
+    let held;
+    try {
+        held = await acquireTargetPlacementFence(repository, state.coordinates.target);
+    }
+    catch (error) {
+        return failed("effect", error);
+    }
+    let result;
+    let exceptional;
+    try {
+        const recovered = recoverTargetPlacement(repository, state);
+        result = complete(recovered.effects, recovered.lag);
+    }
+    catch (error) {
+        if (error instanceof AuthorityCorruptionError || error instanceof TypeError)
+            exceptional = error;
+        else
+            result = failed("effect", error);
+    }
+    let releaseFailure;
+    try {
+        held.close();
+    }
+    catch (error) {
+        releaseFailure = error;
+    }
+    if (exceptional !== undefined)
+        throw exceptional;
+    if (result === undefined)
+        throw new Error("target checkout reconcile produced no result");
+    if (releaseFailure !== undefined)
+        result = failed("effect", releaseFailure, result.effects, result.lag);
+    return result;
+}
+function reconcileHereWorkspaceRefs({ repository }, state, { effects, lag }) {
+    const pin = candidatePinRefFor(state.id);
+    if (state.terminal) {
+        if (state.delivery === null)
+            effects.push(removeRef(repository, pin));
+        else {
+            const integration = state.delivery.data.integration.snapshot;
+            const custodian = snapshotCustodian(repository, integration);
+            effects.push(custodian === null
+                ? updateRef(repository, pin, integration)
+                : removeRefWithCustody(repository, pin, custodian.ref, custodian.oid));
+        }
+    }
+    else if (state.bound) {
+        effects.push(state.delivery === null
+            ? removeRef(repository, pin)
+            : updateRef(repository, pin, state.delivery.data.integration.snapshot));
+    }
+    return complete(effects, lag);
+}
+function retainTerminalWorktree(path, retainedLag, { effects, lag }) {
+    effects.push({ kind: "worktree", path, action: "unchanged" });
+    lag.push(retainedLag);
+    return complete(effects, lag);
+}
+async function terminalSealExpectations(channel, state) {
+    const snapshots = terminalSealSnapshots(state);
+    const objects = await channel.readObjects(snapshots.map(gitObjectIdForSnapshot));
+    return decodeTerminalSealExpectations(state, objects);
+}
+async function removeSealedTerminalWorktree({ repository, topology, path, expected, hooks, retryHooks, acc }) {
+    if (topology.paths.has(path) && existsSync(path)) {
+        const beforeHooks = unsealedBytes(repository, path, expected);
+        if (beforeHooks !== null)
+            return retainTerminalWorktree(path, beforeHooks, acc);
+        const hookLag = await runDestroyHooks(path, worktreeGitDirectory(repository, path), hooks, retryHooks);
+        if (hookLag !== null)
+            return retainTerminalWorktree(path, hookLag, acc);
+        const afterHooks = unsealedBytes(repository, path, expected);
+        if (afterHooks !== null)
+            return retainTerminalWorktree(path, afterHooks, acc);
+    }
+    const removal = removeWorktree(repository, topology, path, true);
+    if (removal.retained)
+        return retainTerminalWorktree(path, { kind: "worktree-retained", path }, acc);
+    acc.effects.push(removal.effect);
+    return null;
+}
+function targetCustodyForClaimedIntegration(repository, state, integration) {
+    return state.terminal?.kind === "claimed" && state.coordinates.target !== undefined
+        && readRef(repository, state.coordinates.target) === integration
+        ? { ref: state.coordinates.target, oid: integration }
+        : null;
+}
+function sealedTree(expected, snapshot) {
+    const tree = expected.treeBySnapshot.get(snapshot);
+    if (tree === undefined)
+        throw new Error(`terminal seal tree was not resolved: ${snapshot}`);
+    return tree;
+}
+function releaseTerminalCustody({ repository, state, expected, ref, pin, acc: { effects } }) {
+    if (state.delivery === null) {
+        const custodian = snapshotCustodian(repository, state.coordinates.start);
+        if (custodian !== null)
+            effects.push(removeRefWithCustody(repository, ref, custodian.ref, custodian.oid));
+        effects.push(removeRef(repository, pin));
+        return;
+    }
+    const tender = state.delivery.data.tenderSnapshot;
+    const integration = state.delivery.data.integration.snapshot;
+    const target = targetCustodyForClaimedIntegration(repository, state, integration);
+    if (sealedTree(expected, tender) === sealedTree(expected, integration) && target !== null) {
+        effects.push(removeRefWithCustody(repository, ref, target.ref, target.oid));
+        effects.push(removeRefWithCustody(repository, pin, target.ref, target.oid));
+    }
+    else if (tender === integration) {
+        effects.push(removeRefWithCustody(repository, pin, ref, tender));
+    }
+    else if (target !== null) {
+        effects.push(removeRefWithCustody(repository, pin, target.ref, target.oid));
+    }
+}
+async function reconcileTerminalManagedWorktree({ repository, channel, hooks, retryHooks, retainTerminalWorktree }, state, topology, acc) {
+    const primary = fromPrimaryWorktree(repository);
+    const ref = deliveryRefFor(state.id);
+    const pin = candidatePinRefFor(state.id);
+    const path = deliveryWorktreePath(repository, state.id);
+    const expected = await terminalSealExpectations(channel, state);
+    acc.effects.push(updateRef(primary, ref, state.delivery?.data.tenderSnapshot ?? state.coordinates.start));
+    if (state.delivery !== null)
+        acc.effects.push(updateRef(primary, pin, state.delivery.data.integration.snapshot));
+    if (retainTerminalWorktree === true)
+        return complete(acc.effects, acc.lag);
+    const retained = await removeSealedTerminalWorktree({ repository: primary, topology, path, expected, hooks, retryHooks, acc });
+    if (retained !== null)
+        return retained;
+    releaseTerminalCustody({ repository: primary, state, expected, ref, pin, acc });
+    return complete(acc.effects, acc.lag);
+}
+async function reconcileActiveManagedWorktree({ repository, hooks, retryHooks }, state, topology, { effects, lag }) {
+    const path = deliveryWorktreePath(repository, state.id);
+    const desired = state.delivery?.data.tenderSnapshot ?? state.coordinates.start;
+    effects.push(updateRef(repository, deliveryRefFor(state.id), desired));
+    effects.push(worktree(repository, topology, path, desired));
+    const hookLag = await runCreateHooks(path, worktreeGitDirectory(repository, path), hooks, retryHooks);
+    if (hookLag !== null)
+        lag.push(hookLag);
+    effects.push(state.delivery
+        ? updateRef(repository, candidatePinRefFor(state.id), state.delivery.data.integration.snapshot)
+        : removeRef(repository, candidatePinRefFor(state.id)));
+    return complete(effects, lag);
+}
+async function reconcileWithTopology(input, state, topology) {
+    const { repository } = input;
+    const effects = [];
+    const lag = [];
+    try {
+        removeOrphanedScratch(repository, topology, effects, lag);
+        if (!state)
+            return complete(effects, lag);
+        const targetCheckouts = await reconcileTargetCheckouts(repository, state);
+        effects.push(...targetCheckouts.effects);
+        lag.push(...targetCheckouts.lag);
+        if (state.coordinates.workspace === "here")
+            return reconcileHereWorkspaceRefs(input, state, { effects, lag });
+        if (state.terminal)
+            return await reconcileTerminalManagedWorktree(input, state, topology, { effects, lag });
+        return await reconcileActiveManagedWorktree(input, state, topology, { effects, lag });
+    }
+    catch (error) {
+        return failed("effect", error, effects, lag);
+    }
+}
+function releaseFailure(held, observation) {
+    try {
+        held.close();
+        return observation;
+    }
+    catch (error) {
+        const prior = observation?.result;
+        return {
+            state: observation?.state ?? null,
+            result: failed("effect", error, prior?.effects, prior?.lag),
+        };
+    }
+}
+export async function reconcile(input) {
+    let held;
+    try {
+        held = await acquireSqliteTransactionLock({
+            path: reconcileLockPath(input.repository, input.contractId),
+            mode: "immediate",
+        });
+    }
+    catch (error) {
+        return { state: null, result: failed("observation", error) };
+    }
+    let observation;
+    let exceptional;
+    try {
+        const state = (await observeContractAt(input.repository, input.channel, input.contractId)).state;
+        const topology = acquireWorktreeTopology(input.repository);
+        observation = {
+            state,
+            result: await reconcileWithTopology(input, state, topology),
+        };
+    }
+    catch (error) {
+        if (error instanceof AuthorityCorruptionError || error instanceof TypeError)
+            exceptional = error;
+        else
+            observation = { state: null, result: failed("observation", error) };
+    }
+    observation = releaseFailure(held, observation);
+    if (exceptional !== undefined)
+        throw exceptional;
+    if (observation === undefined)
+        throw new Error("reconcile produced no observation");
+    return observation;
+}
+export function reconcileObservationFailure(error) {
+    return failed("observation", error);
+}
+export function reconcileEffectFailure(error, prior) {
+    return failed("effect", error, prior?.effects, prior?.lag);
+}
+async function reconcileBatchItem(repository, channel, contract, options) {
+    const observation = await reconcile({ repository, channel, contractId: contract, ...options });
+    return {
+        contract,
+        state: observation.state,
+        result: observation.result,
+    };
+}
+/** Reconcile each discovered Contract through its own serialized, fresh observation. */
+export async function reconcileBatch(repository, channel, contracts, options) {
+    const items = [];
+    for (const contract of contracts)
+        items.push(await reconcileBatchItem(repository, channel, contract, options));
+    return items;
+}

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

@@ -0,0 +1,95 @@
+import { type TreeChange, type TreeEntry } from "./tree.js";
+export type { TreeChange } from "./tree.js";
+export declare const GIT_REF = "refs/heads/keiyaku-state";
+export declare const DELIVERY_REF_NAMESPACE = "refs/heads/keiyaku-delivery";
+export declare const CANDIDATE_PIN_REF_NAMESPACE = "refs/heads/keiyaku-candidate";
+export declare const GIT_FORMAT_PATH = "meta/format.json";
+export declare const GIT_FORMAT_BYTES = "{\"version\":4}\n";
+export declare function isKeiyakuOwnedRef(ref: string): boolean;
+export type GitOid = string;
+export type RefPublication = Readonly<{
+    readonly kind: "published";
+}> | Readonly<{
+    readonly kind: "non-published";
+    readonly error: unknown;
+}> | Readonly<{
+    readonly kind: "unknown";
+}>;
+export type GitRefAssertion = Readonly<{
+    readonly ref: string;
+    readonly oid: GitOid;
+}>;
+export type GitRepository = Readonly<{
+    /** The invocation's effective working directory, including a caller -C worktree. */
+    readonly effectiveCwd: string;
+    /** The canonical primary worktree root for this repository. */
+    readonly primaryWorktree: string;
+    /** The canonical common Git directory pinned when this capability is created. */
+    readonly commonDirectory: string;
+}>;
+export type GitSnapshot = Readonly<{
+    readonly commit: GitOid | null;
+    readonly tree: GitOid | null;
+    readonly paths: ReadonlyMap<string, TreeEntry>;
+}>;
+export declare class NoGitWorldError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+export declare class GitPlumbingError extends Error {
+    readonly stdout: Buffer;
+    readonly stderr: Buffer;
+    readonly status: number | null;
+    readonly pid: number | null;
+    constructor(input: Readonly<{
+        stdout?: string | Uint8Array;
+        stderr: string | Uint8Array;
+        status: number | null;
+        message: string;
+        pid?: number | null;
+    }>);
+}
+export type RegisteredWorktree = Readonly<{
+    path: string;
+    branch: string | null;
+}>;
+export declare function registeredWorktrees(repository: GitRepository): readonly RegisteredWorktree[];
+export declare function registeredWorktreePaths(repository: GitRepository): readonly string[];
+export declare function repositoryAt(cwd: string): GitRepository;
+export declare function commonGitDirectory(repository: GitRepository): string;
+export declare function worktreeGitDirectory(repository: GitRepository, worktree: string): string;
+export declare function worktreeRoot(repository: GitRepository): string;
+export declare function runGit(repository: GitRepository, args: readonly string[], input?: string | Uint8Array): Buffer;
+export declare function runGitWithEnvironment(repository: GitRepository, args: readonly string[], input: string | Uint8Array | undefined, environment: NodeJS.ProcessEnv): Buffer;
+export declare function readRef(repository: GitRepository, ref: string): GitOid | null;
+export declare function readTreeEntries(repository: GitRepository, tree: GitOid): Map<string, TreeEntry>;
+export declare function readGit(repository: GitRepository): GitSnapshot;
+/** Read only the requested private Git paths from one immutable Git tree. */
+export declare function readGitPaths(repository: GitRepository, requestedPaths: readonly string[]): GitSnapshot;
+/** Add paths from the same immutable Git tree without rereading its ref. */
+export declare function extendGitPaths(repository: GitRepository, snapshot: GitSnapshot, requestedPaths: readonly string[]): GitSnapshot;
+/** Expand a targeted immutable snapshot to its complete already-pinned tree. */
+export declare function expandGitSnapshot(repository: GitRepository, snapshot: GitSnapshot): GitSnapshot;
+export declare function writeBlob(repository: GitRepository, bytes: string | Uint8Array): GitOid;
+export declare function readBlob(repository: GitRepository, oid: GitOid): Buffer;
+/** Copy only the changed paths' tree ancestors, preserving untouched subtrees by object ID. */
+export declare function updateGitTree(repository: GitRepository, baseTree: GitOid | null, changes: ReadonlyMap<string, TreeChange>): GitOid;
+/** Write a tree update from directory entries frozen with the admitted base tree. */
+export declare function updateGitTreeFromFrozenDirectories(repository: GitRepository, baseTree: GitOid | null, directories: ReadonlyMap<string, ReadonlyMap<string, TreeEntry>>, changes: ReadonlyMap<string, TreeChange>): GitOid;
+export declare function writeCommit(input: Readonly<{
+    repository: GitRepository;
+    tree: GitOid;
+    parent: GitOid | null;
+    message?: string;
+    actor?: string;
+    at?: string;
+}>): GitOid;
+export declare function updateRefsAtomically(repository: GitRepository, updates: readonly ({
+    readonly ref: typeof GIT_REF;
+    readonly newOid: GitOid;
+    readonly expectedOid: GitOid | null;
+} | {
+    readonly ref: string;
+    readonly newOid: GitOid;
+    readonly expectedOid: GitOid;
+})[], assertions?: readonly GitRefAssertion[]): RefPublication;