@astrosheep/keiyaku 2.9.8 → 2.9.10

package/build/core/repository-ledger/write-transaction.js

@@ -0,0 +1,339 @@
+import { runGitProcess } from "../../git/core.js";
+import { commitRefTransaction, } from "../../git/refs.js";
+import { REPOSITORY_LEDGER_REF, evidenceObjectId, formatLifecycleEntry, formatLifecycleTransaction, repositoryDeliveryRef, } from "./codec.js";
+import { assertHostObjectId, assertReadableCommit, deriveHostGitCoordinates, } from "./git-object-store.js";
+import { assertHonestClaimEvidence } from "./claim-evidence.js";
+import { transactionMembershipError } from "./transaction-membership.js";
+function replayFailure(effect, error) {
+    const source = error;
+    return {
+        effect,
+        status: "failed",
+        cause: {
+            code: typeof source?.code === "string" ? source.code : "REPLAY_FAILED",
+            message: typeof source?.message === "string" ? source.message : String(error),
+        },
+    };
+}
+function validateReplayPlan(plan) {
+    if (plan === undefined)
+        return;
+    const preceding = new Set();
+    for (const step of plan.steps) {
+        if (!step.effect)
+            throw new Error("replay effect name must not be empty");
+        if (preceding.has(step.effect))
+            throw new Error(`duplicate replay effect ${step.effect}`);
+        for (const dependency of step.dependencies ?? []) {
+            if (!preceding.has(dependency)) {
+                throw new Error(`replay effect ${step.effect} has non-preceding dependency ${dependency}`);
+            }
+        }
+        preceding.add(step.effect);
+    }
+}
+async function executeReplayPlan(plan, context) {
+    if (plan === undefined || plan.steps.length === 0) {
+        return {
+            committedHead: context.ledgerHead,
+            status: "contained",
+            effects: [{
+                    effect: "replay-plan",
+                    status: "not-attempted",
+                    dependency: plan === undefined ? "replay-plan-not-provided" : "replay-plan-empty",
+                }],
+        };
+    }
+    const effects = [];
+    const outcomes = new Map();
+    for (const step of plan.steps) {
+        const blockedBy = (step.dependencies ?? []).find((dependency) => outcomes.get(dependency)?.status !== "succeeded");
+        let effect;
+        if (blockedBy !== undefined) {
+            effect = { effect: step.effect, status: "not-attempted", dependency: blockedBy };
+        }
+        else {
+            try {
+                await step.run(context);
+                effect = { effect: step.effect, status: "succeeded" };
+            }
+            catch (error) {
+                effect = replayFailure(step.effect, error);
+            }
+        }
+        effects.push(effect);
+        outcomes.set(step.effect, effect);
+    }
+    return {
+        committedHead: context.ledgerHead,
+        status: effects.every((effect) => effect.status === "succeeded") ? "complete" : "contained",
+        effects,
+    };
+}
+async function assertAuthoritativeCommitTipClosure(cwd, coordinates, operations) {
+    const checked = new Set();
+    for (const operation of operations) {
+        if (operation.kind !== "update" || operation.ref === REPOSITORY_LEDGER_REF || checked.has(operation.newOid))
+            continue;
+        assertHostObjectId(coordinates, operation.newOid);
+        await assertReadableCommit(cwd, coordinates, operation.newOid);
+        checked.add(operation.newOid);
+    }
+}
+export async function buildLifecycleEntry(cwd, entry, expectedLedgerHead) {
+    const coordinates = await deriveHostGitCoordinates(cwd);
+    if (expectedLedgerHead !== null)
+        assertHostObjectId(coordinates, expectedLedgerHead);
+    const evidence = evidenceObjectId(entry);
+    if (evidence !== null) {
+        assertHostObjectId(coordinates, evidence);
+        await assertReadableCommit(cwd, coordinates, evidence);
+    }
+    const parents = [
+        ...(expectedLedgerHead === null ? [] : [expectedLedgerHead]),
+        ...(evidence === null ? [] : [evidence]),
+    ];
+    const args = ["commit-tree", coordinates.emptyTree, ...parents.flatMap((parent) => ["-p", parent])];
+    const result = await runGitProcess(cwd, args, {
+        input: formatLifecycleEntry(entry, coordinates.objectFormat),
+        env: {
+            GIT_AUTHOR_NAME: "Keiyaku",
+            GIT_AUTHOR_EMAIL: "keiyaku@localhost",
+            GIT_COMMITTER_NAME: "Keiyaku",
+            GIT_COMMITTER_EMAIL: "keiyaku@localhost",
+            GIT_AUTHOR_DATE: entry.at,
+            GIT_COMMITTER_DATE: entry.at,
+        },
+    });
+    if (result.status !== 0 || result.error) {
+        const detail = result.stderr.trim() || result.error?.message || `exit ${String(result.status)}`;
+        throw new Error(`cannot build ${entry.kind} ledger object: ${detail}`, { cause: result.error });
+    }
+    const objectId = result.stdout.trim();
+    assertHostObjectId(coordinates, objectId);
+    return { entry, objectId, expectedLedgerHead, parents, coordinates };
+}
+export async function buildLifecycleTail(cwd, entries, expectedLedgerHead) {
+    if (entries.length === 0)
+        throw new Error("a lifecycle tail requires at least one entry");
+    const built = [];
+    let parent = expectedLedgerHead;
+    for (const entry of entries) {
+        const next = await buildLifecycleEntry(cwd, entry, parent);
+        built.push(next);
+        parent = next.objectId;
+    }
+    return { entries: built, expectedLedgerHead };
+}
+export async function buildLifecycleTransactionNode(input) {
+    if (input.entries.length === 0)
+        throw new Error("a lifecycle transaction requires at least one introduced entry");
+    const coordinates = input.entries[0].coordinates;
+    if (input.entries.some((entry) => entry.coordinates.objectFormat !== coordinates.objectFormat
+        || entry.coordinates.emptyTree !== coordinates.emptyTree
+        || entry.coordinates.objectIdLength !== coordinates.objectIdLength)) {
+        throw new Error("lifecycle transaction entries use inconsistent host coordinates");
+    }
+    if (input.predecessor !== null)
+        assertHostObjectId(coordinates, input.predecessor);
+    const membership = transactionMembershipError(input.verb, input.entries.map((entry) => entry.entry));
+    if (membership)
+        throw new Error(membership);
+    const first = input.entries[0];
+    if (input.verb === "bind" && first.expectedLedgerHead !== null) {
+        throw new Error("bind transaction member must be causally parentless");
+    }
+    if (input.verb !== "bind" && first.expectedLedgerHead === null) {
+        throw new Error(`${input.verb} transaction must continue lifecycle causality`);
+    }
+    for (let index = 1; index < input.entries.length; index += 1) {
+        if (input.entries[index].expectedLedgerHead !== input.entries[index - 1].objectId) {
+            throw new Error("transaction members must form one ordered lifecycle causal tail");
+        }
+    }
+    const transaction = {
+        v: 1,
+        kind: "transaction",
+        verb: input.verb,
+        predecessor: input.predecessor === null ? "none" : "p1",
+    };
+    const parents = [
+        ...(input.predecessor === null ? [] : [input.predecessor]),
+        ...input.entries.map((entry) => entry.objectId),
+    ];
+    if (new Set(parents).size !== parents.length)
+        throw new Error("transaction links and predecessor must be distinct");
+    const final = input.entries.at(-1);
+    const result = await runGitProcess(input.cwd, ["commit-tree", coordinates.emptyTree, ...parents.flatMap((parent) => ["-p", parent])], {
+        input: formatLifecycleTransaction(transaction),
+        env: {
+            GIT_AUTHOR_NAME: "Keiyaku",
+            GIT_AUTHOR_EMAIL: "keiyaku@localhost",
+            GIT_COMMITTER_NAME: "Keiyaku",
+            GIT_COMMITTER_EMAIL: "keiyaku@localhost",
+            GIT_AUTHOR_DATE: final.entry.at,
+            GIT_COMMITTER_DATE: final.entry.at,
+        },
+    });
+    if (result.status !== 0 || result.error) {
+        const detail = result.stderr.trim() || result.error?.message || `exit ${String(result.status)}`;
+        throw new Error(`cannot build ${input.verb} transaction node: ${detail}`, { cause: result.error });
+    }
+    const objectId = result.stdout.trim();
+    assertHostObjectId(coordinates, objectId);
+    return {
+        transaction,
+        objectId,
+        predecessor: input.predecessor,
+        entryObjectIds: input.entries.map((entry) => entry.objectId),
+        parents,
+        coordinates,
+    };
+}
+async function buildTransactionTail(input) {
+    const contract = input.entries.at(-1)?.contract;
+    if (!contract)
+        throw new Error("a lifecycle transaction requires one contract identity");
+    const causalParent = input.acceptedLifecycleTail;
+    if (input.verb === "bind" && causalParent !== null)
+        throw new Error(`bind transaction repeats contract ${contract}`);
+    if (input.verb !== "bind" && causalParent === null)
+        throw new Error(`${input.verb} transaction has no accepted lifecycle predecessor for ${contract}`);
+    const tail = await buildLifecycleTail(input.cwd, input.entries, causalParent);
+    const transaction = await buildLifecycleTransactionNode({
+        cwd: input.cwd,
+        verb: input.verb,
+        predecessor: input.predecessor,
+        entries: tail.entries,
+    });
+    return { tail, transaction };
+}
+async function publishLifecycleWrite(cwd, builtTransaction, final, ownedOperations, replayPlan, transactionRunner) {
+    validateReplayPlan(replayPlan);
+    const authoritativeOperations = [
+        { kind: "update", ref: REPOSITORY_LEDGER_REF, newOid: builtTransaction.objectId, expectedOldOid: builtTransaction.predecessor },
+        ...ownedOperations,
+    ];
+    await assertAuthoritativeCommitTipClosure(cwd, builtTransaction.coordinates, authoritativeOperations);
+    const transaction = await commitRefTransaction(cwd, authoritativeOperations, builtTransaction.coordinates.objectIdLength, {
+        ...(transactionRunner === undefined ? {} : { run: transactionRunner }),
+    });
+    if (transaction.status === "refused") {
+        return {
+            family: "refused-before-effects",
+            code: transaction.code,
+            builtLedgerHead: builtTransaction.objectId,
+            observations: transaction.observations,
+            cause: transaction.cause,
+        };
+    }
+    if (transaction.status === "indeterminate") {
+        return {
+            family: "indeterminate",
+            code: transaction.code,
+            builtLedgerHead: builtTransaction.objectId,
+            observations: transaction.observations,
+            cause: transaction.cause,
+        };
+    }
+    const replay = await executeReplayPlan(replayPlan, {
+        ledgerHead: builtTransaction.objectId,
+        entry: final.entry,
+        authoritativeOperations,
+    });
+    return {
+        family: "committed",
+        completion: replay.status,
+        ledgerHead: builtTransaction.objectId,
+        entry: final.entry,
+        authoritativeOperations,
+        authorityProof: transaction.proof,
+        authorityObservations: transaction.observations,
+        replay,
+    };
+}
+export async function publishBindTransaction(input) {
+    const expectedDeliveryRef = repositoryDeliveryRef(input.entry.contract);
+    if (input.delivery.ref !== expectedDeliveryRef) {
+        throw new Error(`bind delivery ref must be ${expectedDeliveryRef}`);
+    }
+    if (input.delivery.head !== input.entry.data.base) {
+        throw new Error("bind delivery head must equal the entry base");
+    }
+    const selectedTasks = input.entry.data.taskIds !== undefined;
+    if (selectedTasks !== (input.taskBoard !== undefined)) {
+        throw new Error("bind taskIds and task-board transaction must be present together");
+    }
+    if (input.taskBoard && input.taskBoard.head !== input.entry.data.base) {
+        throw new Error("task-selected bind base must equal the new task-board head");
+    }
+    const built = await buildTransactionTail({
+        cwd: input.cwd,
+        verb: "bind",
+        predecessor: input.expectedLedgerHead,
+        acceptedLifecycleTail: null,
+        entries: [input.entry],
+    });
+    const operations = [
+        { kind: "update", ref: input.delivery.ref, newOid: input.delivery.head, expectedOldOid: null },
+    ];
+    if (input.taskBoard) {
+        operations.push({
+            kind: "update",
+            ref: input.taskBoard.ref,
+            newOid: input.taskBoard.head,
+            expectedOldOid: input.taskBoard.expectedHead,
+        });
+    }
+    return await publishLifecycleWrite(input.cwd, built.transaction, built.tail.entries[0], operations, input.replayPlan, input.transactionRunner);
+}
+function assertAuthority(condition, message) {
+    if (!condition)
+        throw new Error(message);
+}
+function assertAuthoritativeTail(transaction) {
+    const error = transactionMembershipError(transaction.verb, transaction.entries);
+    assertAuthority(error === null, error?.replace(`${transaction.verb} transaction`, `${transaction.verb} authoritative transaction`)
+        ?? "invalid authoritative transaction membership");
+}
+/** Build and commit exactly the semantic authority selected by one lifecycle verb. */
+export async function publishAuthoritativeTransaction(cwd, transaction, options = {}) {
+    assertAuthoritativeTail(transaction);
+    const built = await buildTransactionTail({
+        cwd,
+        verb: transaction.verb,
+        predecessor: transaction.admittedLedgerHead,
+        acceptedLifecycleTail: transaction.acceptedLifecycleTail,
+        entries: transaction.entries,
+    });
+    const builtTail = built.tail;
+    const final = builtTail.entries.at(-1);
+    const entry = final.entry;
+    const operations = [];
+    if (transaction.verb === "renew" && entry.kind === "renew") {
+        assertAuthority("delivery" in transaction, "renew transaction must pin its delivery ref");
+        assertAuthority(transaction.delivery.ref === repositoryDeliveryRef(entry.contract), "renew delivery ref does not name its contract");
+        assertAuthority(transaction.delivery.expectedOid === entry.data.oldHead, "renew delivery CAS must equal oldHead");
+        assertAuthority(entry.data.oldHead !== entry.data.newHead, "renew must replace the delivery head");
+        operations.push({ kind: "update", ref: transaction.delivery.ref, expectedOldOid: transaction.delivery.expectedOid, newOid: entry.data.newHead });
+    }
+    else if (transaction.verb === "forfeit") {
+        assertAuthority(entry.kind === "forfeit", "forfeit transaction must end in a forfeit entry");
+        assertAuthority(transaction.delivery.ref === repositoryDeliveryRef(entry.contract), "forfeit delivery ref does not name its contract");
+        assertAuthority(transaction.delivery.expectedOid === null || transaction.delivery.expectedOid === entry.data.finalHead, "forfeit delivery CAS must equal finalHead or prove absence");
+        operations.push(transaction.delivery.expectedOid === null
+            ? { kind: "verify", ref: transaction.delivery.ref, expectedOldOid: null }
+            : { kind: "delete", ref: transaction.delivery.ref, expectedOldOid: transaction.delivery.expectedOid });
+    }
+    else if (transaction.verb === "claim") {
+        assertAuthority(entry.kind === "claim", "claim transaction must end in a claim entry");
+        assertAuthority(transaction.target.ref === entry.data.target, "claim target ref must equal the accepted entry target");
+        assertAuthority(transaction.target.expectedOid === entry.data.targetHead, "claim target CAS must equal targetHead");
+        assertAuthority(transaction.delivery.ref === repositoryDeliveryRef(entry.contract), "claim delivery ref does not name its contract");
+        assertAuthority(transaction.delivery.expectedOid === entry.data.deliveryHead, "claim delivery CAS must equal deliveryHead");
+        await assertHonestClaimEvidence(cwd, entry.data);
+        operations.push({ kind: "update", ref: transaction.target.ref, expectedOldOid: transaction.target.expectedOid, newOid: entry.data.mergeCommit }, { kind: "delete", ref: transaction.delivery.ref, expectedOldOid: transaction.delivery.expectedOid });
+    }
+    const write = await publishLifecycleWrite(cwd, built.transaction, final, operations, options.replayPlan, options.transactionRunner);
+    return { builtTail, builtTransaction: built.transaction, write };
+}