@astrosheep/keiyaku 2.9.13 → 4.0.0

package/build/src/git/hooks.js

@@ -0,0 +1,258 @@
+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";
+const MARKER_VERSION = 1;
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+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;
+}
+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 failure = failedOutcome(await runProcess({
+            argv: command.argv,
+            timeoutMs: command.timeoutMs,
+            cwd: input.worktree,
+        }));
+        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,13 @@
+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 contractJournalPath(contract: ContractId): 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,28 @@
+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})$/;
+export function contractLocator(contract) {
+    const id = contractId(contract);
+    return createHash("sha256").update(id, "utf8").digest("hex");
+}
+export function contractJournalPath(contract) {
+    const digest = contractLocator(contract);
+    return `contracts/${digest.slice(0, 2)}/${digest.slice(2, 4)}/${digest.slice(4)}.jsonl`;
+}
+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/observe.d.ts

@@ -0,0 +1,38 @@
+import { type ContractId, type ContractState, type JournalEntry, type SnapshotId } from "../core/facts/types.js";
+import type { ContractsObservation } from "../core/facts/observation.js";
+import { type GitSnapshot, type GitOid, type GitRepository } from "./repository.js";
+type GitJournalRecord = Readonly<{
+    entries: readonly JournalEntry[];
+    state: ContractState | null;
+}>;
+type GitObservation = Readonly<{
+    contracts: ReadonlyMap<ContractId, GitJournalRecord>;
+}>;
+export type GitAdmissionSnapshot = Readonly<{
+    snapshot: GitSnapshot;
+    frozenJournalBytes: ReadonlyMap<GitOid, Buffer>;
+}>;
+export type GitDecisionObservation = Readonly<{
+    admission: GitAdmissionSnapshot;
+    decision: ContractsObservation;
+    journals: ReadonlyMap<ContractId, GitJournalRecord>;
+}>;
+type BindCoordinatesObservation = Readonly<{
+    start: SnapshotId;
+    target?: string;
+}>;
+export declare function normalizeTargetBranch(repository: GitRepository, input: string): string | null;
+/** Read the effective worktree's attached branch, or null for detached HEAD. */
+export declare function currentBranch(repository: GitRepository): string | null;
+/** Observe bind's tender start and optional reward target without creating persistent state. */
+export declare function observeBindCoordinates(repository: GitRepository, requestedTarget?: string): BindCoordinatesObservation | null;
+/** Read one immutable Git snapshot, enumerate its journals, and include requested absence. */
+export declare function observeGit(repository: GitRepository, requested?: readonly ContractId[]): GitObservation;
+/** Read one Git tree and fold all requested contracts from that immutable snapshot. */
+export declare function observeContracts(repository: GitRepository, ids: readonly ContractId[]): GitObservation;
+export declare function observeContractsForAdmission(repository: GitRepository, ids: readonly ContractId[]): GitDecisionObservation;
+/** Extend one admission observation with contracts from its already-pinned tree. */
+export declare function extendContractsForAdmission(repository: GitRepository, observation: GitDecisionObservation, ids: readonly ContractId[]): GitDecisionObservation;
+export declare function observeGitForAdmission(repository: GitRepository, ids: readonly ContractId[]): GitDecisionObservation;
+export declare function observeContract(repository: GitRepository, id: ContractId): GitJournalRecord;
+export {};

package/build/src/git/observe.js

@@ -0,0 +1,227 @@
+import { decodeJournal } from "../core/facts/codec.js";
+import { AuthorityCorruptionError } from "../core/facts/errors.js";
+import { foldJournal } from "../core/facts/fold.js";
+import { contractJournalPath, mintContractHead, mintSnapshotId } from "./identity.js";
+import { GitPlumbingError, isKeiyakuOwnedRef, extendGitPaths, readBlobs, readGit, readGitPaths, runGit, } from "./repository.js";
+const TARGET_COORDINATES_FORMAT = "%(refname)%00%(objectname)%00";
+export function normalizeTargetBranch(repository, input) {
+    if (input.includes("\0"))
+        return null;
+    const prefix = "refs/heads/";
+    if (input.startsWith("refs/") && !input.startsWith(prefix))
+        return null;
+    const branch = input.startsWith(prefix) ? input.slice(prefix.length) : input;
+    const target = `${prefix}${branch}`;
+    if (branch.length === 0 || branch.startsWith("-") || isKeiyakuOwnedRef(target))
+        return null;
+    try {
+        const checked = runGit(repository, ["check-ref-format", "--branch", branch]).toString("utf8").trim();
+        return checked === branch ? target : null;
+    }
+    catch (error) {
+        if (error instanceof GitPlumbingError && error.status !== null)
+            return null;
+        throw error;
+    }
+}
+/** Read the effective worktree's attached branch, or null for detached HEAD. */
+export function currentBranch(repository) {
+    try {
+        const ref = runGit(repository, ["symbolic-ref", "--quiet", "HEAD"]).toString("utf8").trim();
+        return ref.startsWith("refs/heads/") ? ref : null;
+    }
+    catch (error) {
+        if (error instanceof GitPlumbingError && error.status === 1)
+            return null;
+        throw error;
+    }
+}
+function malformedBindCoordinatesOutput() {
+    throw new Error("malformed structured Git output while observing bind coordinates");
+}
+function structuredFields(output, fieldCount) {
+    const fields = output.toString("utf8").split("\0");
+    if (fields.length !== fieldCount + 1 || fields.at(-1) !== "\n")
+        malformedBindCoordinatesOutput();
+    return fields.slice(0, -1);
+}
+/** Observe bind's tender start and optional reward target without creating persistent state. */
+export function observeBindCoordinates(repository, requestedTarget) {
+    if (requestedTarget === undefined) {
+        try {
+            return { start: mintSnapshotId(runGit(repository, ["rev-parse", "--verify", "HEAD"]).toString("utf8").trim()) };
+        }
+        catch {
+            malformedBindCoordinatesOutput();
+        }
+    }
+    if (isKeiyakuOwnedRef(requestedTarget)) {
+        throw new Error(`bind target names a Keiyaku-owned ref: ${requestedTarget}`);
+    }
+    const output = runGit(repository, [
+        "for-each-ref",
+        `--format=${TARGET_COORDINATES_FORMAT}`,
+        "--",
+        requestedTarget,
+    ]);
+    if (output.length === 0)
+        return null;
+    const [target, start] = structuredFields(output, 2);
+    if (target !== requestedTarget || start === undefined)
+        malformedBindCoordinatesOutput();
+    try {
+        return { target, start: mintSnapshotId(start) };
+    }
+    catch {
+        malformedBindCoordinatesOutput();
+    }
+}
+function decodeGitJournal(path, git, bytes, expectedId) {
+    const journal = git.paths.get(path);
+    if (journal === undefined)
+        throw new AuthorityCorruptionError(`missing Git journal: ${path}`);
+    if (journal.type !== "blob")
+        throw new AuthorityCorruptionError(`journal path is not a blob: ${path}`);
+    const entries = decodeJournal(bytes.toString("utf8"));
+    const first = entries[0];
+    if (first === undefined
+        || (expectedId !== undefined && first.contract !== expectedId)
+        || entries.some((entry) => entry.contract !== (expectedId ?? first.contract))) {
+        if (expectedId !== undefined) {
+            throw new AuthorityCorruptionError(`journal content does not canonically identify ${expectedId}: ${path}`);
+        }
+        throw new AuthorityCorruptionError(`journal content does not canonically identify ${path}`);
+    }
+    const id = first.contract;
+    if (contractJournalPath(id) !== path) {
+        throw new AuthorityCorruptionError(`journal path does not match canonical contract identity: ${path}`);
+    }
+    return { id, entries, oid: journal.oid };
+}
+function observeDecodedJournal(id, decoded) {
+    return {
+        entries: decoded.entries,
+        state: foldJournal(id, decoded.entries, mintContractHead(decoded.oid)),
+    };
+}
+function observeFromGit(git, id, blobs) {
+    const path = contractJournalPath(id);
+    const journal = git.paths.get(path);
+    if (journal === undefined)
+        return { entries: [], state: null };
+    if (journal.type !== "blob")
+        throw new AuthorityCorruptionError(`journal path is not a blob: ${path}`);
+    const bytes = blobs.get(journal.oid);
+    if (bytes === undefined)
+        throw new Error(`missing batched journal bytes: ${path}`);
+    const decoded = decodeGitJournal(path, git, bytes, id);
+    return observeDecodedJournal(id, decoded);
+}
+function enumerateContractObservations(git, blobs) {
+    const observations = new Map();
+    const seen = new Set();
+    for (const [path, journal] of git.paths) {
+        if (!path.startsWith("contracts/") || !path.endsWith(".jsonl"))
+            continue;
+        if (journal.type !== "blob")
+            throw new AuthorityCorruptionError(`journal path is not a blob: ${path}`);
+        const bytes = blobs.get(journal.oid);
+        if (bytes === undefined)
+            throw new Error(`missing batched journal bytes: ${path}`);
+        const decoded = decodeGitJournal(path, git, bytes);
+        const id = decoded.id;
+        if (seen.has(id))
+            throw new AuthorityCorruptionError(`duplicate contract journal identity: ${id}`);
+        seen.add(id);
+        observations.set(id, observeDecodedJournal(id, decoded));
+    }
+    return observations;
+}
+/** Read one immutable Git snapshot, enumerate its journals, and include requested absence. */
+export function observeGit(repository, requested = []) {
+    const git = readGit(repository);
+    const observed = observeFrozenGitSnapshot(repository, git, requested);
+    return { contracts: observed.contracts };
+}
+function observeFrozenGitSnapshot(repository, git, requested) {
+    const blobs = readBlobs(repository, [...git.paths]
+        .filter(([path, entry]) => path.startsWith("contracts/") && path.endsWith(".jsonl") && entry.type === "blob")
+        .map(([, entry]) => entry.oid));
+    const contracts = new Map(enumerateContractObservations(git, blobs));
+    for (const id of requested) {
+        if (!contracts.has(id))
+            contracts.set(id, observeFromGit(git, id, blobs));
+    }
+    return {
+        contracts,
+        frozenJournalBytes: blobs,
+    };
+}
+/** Read one Git tree and fold all requested contracts from that immutable snapshot. */
+export function observeContracts(repository, ids) {
+    const git = readGitPaths(repository, ids.map((id) => contractJournalPath(id)));
+    const observed = observeFrozenContractsSnapshot(repository, git, ids);
+    return { contracts: observed.contracts };
+}
+function observeFrozenContractsSnapshot(repository, git, ids) {
+    const contracts = new Map();
+    const paths = ids.map((id) => contractJournalPath(id));
+    const blobs = readBlobs(repository, paths.flatMap((path) => {
+        const journal = git.paths.get(path);
+        return journal?.type === "blob" ? [journal.oid] : [];
+    }));
+    for (const id of ids) {
+        if (!contracts.has(id))
+            contracts.set(id, observeFromGit(git, id, blobs));
+    }
+    return {
+        contracts,
+        frozenJournalBytes: blobs,
+    };
+}
+function decisionProjection(observation) {
+    return new Map([...observation.contracts].map(([id, record]) => [id, record.state]));
+}
+export function observeContractsForAdmission(repository, ids) {
+    const git = readGitPaths(repository, ids.map((id) => contractJournalPath(id)));
+    const contracts = observeFrozenContractsSnapshot(repository, git, ids);
+    return {
+        admission: { snapshot: git, frozenJournalBytes: contracts.frozenJournalBytes },
+        decision: decisionProjection(contracts),
+        journals: contracts.contracts,
+    };
+}
+/** Extend one admission observation with contracts from its already-pinned tree. */
+export function extendContractsForAdmission(repository, observation, ids) {
+    const missing = ids.filter((id) => !observation.decision.has(id));
+    if (missing.length === 0)
+        return observation;
+    const snapshot = extendGitPaths(repository, observation.admission.snapshot, missing.map((id) => contractJournalPath(id)));
+    const added = observeFrozenContractsSnapshot(repository, snapshot, missing);
+    return {
+        admission: {
+            snapshot,
+            frozenJournalBytes: new Map([
+                ...observation.admission.frozenJournalBytes,
+                ...added.frozenJournalBytes,
+            ]),
+        },
+        decision: new Map([...observation.decision, ...decisionProjection(added)]),
+        journals: new Map([...observation.journals, ...added.contracts]),
+    };
+}
+export function observeGitForAdmission(repository, ids) {
+    const git = readGit(repository);
+    const contracts = observeFrozenGitSnapshot(repository, git, ids);
+    return {
+        admission: { snapshot: git, frozenJournalBytes: contracts.frozenJournalBytes },
+        decision: decisionProjection(contracts),
+        journals: contracts.contracts,
+    };
+}
+export function observeContract(repository, id) {
+    const observation = observeContracts(repository, [id]).contracts.get(id);
+    if (observation === undefined)
+        throw new Error(`missing requested contract observation: ${id}`);
+    return observation;
+}

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

@@ -0,0 +1,49 @@
+import { type GitOid, type GitRepository } from "./repository.js";
+import { type ContractId, type ContractState } from "../core/facts/types.js";
+import { type WorktreeHookLag, type WorktreeHooks } from "./hooks.js";
+export type Effect = Readonly<{
+    kind: "worktree";
+    path: string;
+    action: "created" | "removed" | "unchanged";
+}> | Readonly<{
+    kind: "ref";
+    name: string;
+    before: GitOid | null;
+    after: GitOid | null;
+    action: "created" | "updated" | "removed" | "unchanged";
+}>;
+type ReconcileInput = Readonly<{
+    repository: GitRepository;
+    contractId: ContractId;
+    hooks: WorktreeHooks;
+    retryHooks: boolean;
+}>;
+type WorktreeRetained = Readonly<{
+    kind: "worktree-retained";
+    path: string;
+}>;
+export type ReconcileFailure = Readonly<{
+    kind: "reconcile-failed";
+    stage: "observation" | "effect";
+    diagnostic: string;
+}>;
+export type ReconcileLag = WorktreeRetained | WorktreeHookLag | ReconcileFailure;
+export type ReconcileResult = Readonly<{
+    effects: readonly Effect[];
+    lag: readonly ReconcileLag[];
+}>;
+type ReconcileBatchItem = Readonly<{
+    contract: ContractId;
+    state: ContractState | null;
+    result: ReconcileResult;
+}>;
+export type GitReconcileObservation = Readonly<{
+    state: ContractState | null;
+    result: ReconcileResult;
+}>;
+export declare function deliveryWorktreePath(repository: GitRepository, contract: ContractId): string;
+export declare function reconcile(input: ReconcileInput): Promise<GitReconcileObservation>;
+export declare function reconcileObservationFailure(error: unknown): ReconcileResult;
+/** Reconcile each discovered Contract through its own serialized, fresh observation. */
+export declare function reconcileBatch(repository: GitRepository, contracts: Iterable<ContractId>, hooks: WorktreeHooks, retryHooks: boolean): Promise<readonly ReconcileBatchItem[]>;
+export {};