@astrosheep/keiyaku 2.9.8 → 2.9.10

package/build/core/contract-carrier-runtime.js

@@ -0,0 +1,408 @@
+import * as fs from "node:fs/promises";
+import { FlowError } from "../flow-error.js";
+import { replayCommittedDerivedState } from "./derived-replay.js";
+import { EffectJournal } from "./outcome-base.js";
+import { readRepositoryLifecycle } from "./repository-ledger/read-model.js";
+import { REPOSITORY_LEDGER_REF } from "./repository-ledger/codec.js";
+import { resolveAcceptedLifecycleTransaction } from "./repository-ledger/accepted-tail.js";
+import { publishAuthoritativeTransaction } from "./repository-ledger/write-transaction.js";
+import { cleanupContractWorkspace, contractWorktreePathFromBind, observeTerminalDeliveryRef, resolveContractCarrierTarget, stableRepoRoot } from "./worktree-path.js";
+import { defaultCreateWorktree } from "./bind-workspace.js";
+import { replayClaimTargetWorktree } from "./settlement/claim-delivery.js";
+let acceptedBind, acquireGate, carrierMatches, checkCancellation;
+let observe, observedLedgerHead, projectRenewDeliveryWorktree, publishCarrier;
+let readCarrierIdentity, reconcileFoldedDeliveryWorktree, releaseGate, resolveCommitOrNull, retireTerminalHereCarrier;
+export function installCarrierRuntimePorts(ports) {
+    ({ acceptedBind, acquireGate, carrierMatches, checkCancellation, observe, observedLedgerHead,
+        projectRenewDeliveryWorktree, publishCarrier, readCarrierIdentity, reconcileFoldedDeliveryWorktree,
+        releaseGate, resolveCommitOrNull, retireTerminalHereCarrier } = ports);
+}
+export async function withContractCarrierSession(input, action) {
+    const stableRoot = await stableRepoRoot(input.cwd);
+    if (input.mode === "observe-only") {
+        checkCancellation(input.signal);
+        const { repository, lifecycle, target, pins } = await observe(stableRoot, input.contractId);
+        const projectedCarrier = target.status === "available" ? await readCarrierIdentity(target.path) : null;
+        const initialCarrier = target.status === "available"
+            ? { status: carrierMatches(projectedCarrier, input.contractId, lifecycle.observedLedgerHead) ? "current" : "stale", ledgerHead: lifecycle.observedLedgerHead, target: target.path }
+            : { status: "target-unavailable", ledgerHead: lifecycle.observedLedgerHead, reason: target.reason };
+        return action(createSession(input.mode, stableRoot, input.contractId, repository, lifecycle, target, pins, initialCarrier, input.signal, input.contractViewWriter, input.renewDeliveryProjector, input.terminalWorkspaceCleanup));
+    }
+    // Closure/fold observation can be comparatively expensive. Do it before the
+    // repository-wide carrier gate, then admit the snapshot only if the sole
+    // authoritative coordinate still names the same ledger tip under the gate.
+    const preGateObserved = await observe(stableRoot, input.contractId);
+    const gate = await acquireGate(stableRoot, input.signal);
+    try {
+        checkCancellation(input.signal);
+        const observedHead = await resolveCommitOrNull(stableRoot, REPOSITORY_LEDGER_REF);
+        const { repository, lifecycle, target, pins } = observedHead === preGateObserved.lifecycle.observedLedgerHead
+            ? preGateObserved
+            : await observe(stableRoot, input.contractId);
+        const projectedCarrier = target.status === "available" ? await readCarrierIdentity(target.path) : null;
+        const initialCarrier = target.status === "available"
+            ? { status: carrierMatches(projectedCarrier, input.contractId, lifecycle.observedLedgerHead) ? "current" : "stale", ledgerHead: lifecycle.observedLedgerHead, target: target.path }
+            : { status: "target-unavailable", ledgerHead: lifecycle.observedLedgerHead, reason: target.reason };
+        checkCancellation(input.signal);
+        const session = createSession(input.mode, stableRoot, input.contractId, repository, lifecycle, target, pins, initialCarrier, input.signal, input.contractViewWriter, input.renewDeliveryProjector, input.terminalWorkspaceCleanup);
+        return await action(session);
+    }
+    finally {
+        releaseGate(gate);
+    }
+}
+function createSession(mode, stableRoot, contractId, repository, lifecycle, target, pins, initialCarrier, signal, contractViewWriter, renewDeliveryProjector, terminalWorkspaceCleanup) {
+    const admittedLedgerHead = lifecycle.observedLedgerHead;
+    const admittedLifecycleTail = lifecycle.history.at(-1)?.objectId;
+    if (!admittedLifecycleTail)
+        throw new FlowError("INTERNAL_STATE", `carrier admission ${contractId} has no accepted lifecycle tail`);
+    let currentLifecycle = lifecycle;
+    let authoritativeTransactionSelected = false;
+    let effectsStarted = false;
+    let committedResult;
+    const journal = new EffectJournal(`${contractId}:${lifecycle.observedLedgerHead}`);
+    async function finalizeCommitted(input) {
+        effectsStarted = true;
+        if (input.renewProjection) {
+            await journal.run({
+                effect: "delivery-worktree-projection",
+                idempotencyKey: `${contractId}:${input.head}:delivery-worktree-projection`,
+                run: async () => (renewDeliveryProjector ?? projectRenewDeliveryWorktree)(input.renewProjection.target, input.renewProjection.oldHead, input.renewProjection.newHead),
+            });
+        }
+        let resolvedTransaction;
+        await journal.run({
+            effect: "committed-ledger-reread",
+            idempotencyKey: `${contractId}:${input.head}:ledger-reread`,
+            run: async () => {
+                const observed = await observe(stableRoot, contractId);
+                currentLifecycle = observed.lifecycle;
+                const accepted = resolveAcceptedLifecycleTransaction({ read: observed.repository, transactionObjectId: input.head, expectedContract: contractId });
+                if (accepted.status !== "accepted")
+                    throw new FlowError("COMMITTED_LEDGER_REREAD_FAILED", `accepted ledger transaction ${input.head} could not be reread (${accepted.reason})`);
+                resolvedTransaction = accepted;
+                return { head: observed.lifecycle.observedLedgerHead };
+            },
+        });
+        journal.beginDerivedReplay();
+        const carrier = input.carrier === "retire"
+            ? { status: "retired", ledgerHead: input.head, reason: "terminal" }
+            : target.status === "available"
+                ? { status: "stale", ledgerHead: currentLifecycle.observedLedgerHead, target: target.path }
+                : { status: "target-unavailable", ledgerHead: currentLifecycle.observedLedgerHead, reason: target.reason };
+        committedResult = {
+            status: "committed",
+            head: input.head,
+            transaction: resolvedTransaction ?? (() => { throw new FlowError("COMMITTED_LEDGER_REREAD_FAILED", `accepted ledger transaction ${input.head} was not reread`); })(),
+            carrier,
+            effects: journal.all(),
+            cancellationObserved: effectsStarted && (signal?.aborted ?? false),
+        };
+        return committedResult;
+    }
+    async function publishRepository(transaction, additionalReplaySteps = []) {
+        if (mode !== "mutation")
+            throw new FlowError("INTERNAL_STATE", `carrier ${mode} session cannot publish repository ledger facts`);
+        if (!effectsStarted)
+            checkCancellation(signal);
+        let replayed;
+        let carrier = target.status === "available"
+            ? { status: "stale", ledgerHead: currentLifecycle.observedLedgerHead, target: target.path }
+            : { status: "target-unavailable", ledgerHead: currentLifecycle.observedLedgerHead, reason: target.reason };
+        const replayPlan = {
+            steps: [
+                ...additionalReplaySteps,
+                {
+                    effect: "committed-ledger-reread",
+                    dependencies: additionalReplaySteps.map((step) => step.effect),
+                    run: async ({ ledgerHead }) => {
+                        replayed = await observe(stableRoot, contractId);
+                        if (replayed.lifecycle.observedLedgerHead !== ledgerHead) {
+                            throw new FlowError("COMMITTED_LEDGER_REREAD_FAILED", `committed ledger head ${ledgerHead} could not be reread (observed ${replayed.lifecycle.observedLedgerHead})`);
+                        }
+                        currentLifecycle = replayed.lifecycle;
+                    },
+                },
+            ],
+        };
+        const publication = await publishAuthoritativeTransaction(stableRoot, transaction, { replayPlan });
+        const result = publication.write;
+        if (result.family === "refused-before-effects") {
+            return {
+                status: "refused-before-effects",
+                reason: "conflict",
+                currentHead: observedLedgerHead(result.observations),
+                code: result.code,
+                cause: result.cause,
+                observations: result.observations,
+                effects: [],
+            };
+        }
+        if (result.family === "indeterminate") {
+            effectsStarted = true;
+            const currentHead = observedLedgerHead(result.observations);
+            journal.record({
+                effect: "ledger-cas",
+                idempotencyKey: `${contractId}:${result.builtLedgerHead}:ledger-cas`,
+                status: "failed",
+                cause: {
+                    code: result.code,
+                    message: result.cause,
+                    facts: { builtHead: result.builtLedgerHead, currentHead },
+                },
+            });
+            return { status: "indeterminate", builtHead: result.builtLedgerHead, currentHead, effects: journal.all() };
+        }
+        effectsStarted = true;
+        const accepted = publication.builtTail.entries.at(-1);
+        const ledgerCasKey = `${contractId}:${result.ledgerHead}:ledger-cas`;
+        journal.record({
+            effect: "ledger-cas",
+            idempotencyKey: ledgerCasKey,
+            status: "succeeded",
+            receipt: {
+                head: result.ledgerHead,
+                entryKind: accepted.entry.kind,
+                authorityProof: result.authorityProof,
+            },
+        });
+        const replayDependencyEffects = {
+            "committed-ledger-reread": additionalReplaySteps.at(-1)?.effect ?? ledgerCasKey,
+        };
+        const replayKeys = new Map();
+        for (const effect of result.replay.effects) {
+            const idempotencyKey = `${contractId}:${result.ledgerHead}:${effect.effect}`;
+            replayKeys.set(effect.effect, idempotencyKey);
+            const dependencyEffect = replayDependencyEffects[effect.effect];
+            const dependency = dependencyEffect === ledgerCasKey ? ledgerCasKey : dependencyEffect ? replayKeys.get(dependencyEffect) : undefined;
+            const row = effect.status === "succeeded"
+                ? { effect: effect.effect, idempotencyKey, ...(dependency ? { dependency } : {}), status: "succeeded" }
+                : effect.status === "failed"
+                    ? { effect: effect.effect, idempotencyKey, ...(dependency ? { dependency } : {}), status: "failed", cause: effect.cause }
+                    : {
+                        effect: effect.effect,
+                        idempotencyKey,
+                        dependency: replayKeys.get(effect.dependency) ?? effect.dependency,
+                        status: "not-attempted",
+                        cause: { code: "DEPENDENCY_FAILED", message: `dependency ${effect.dependency} did not succeed` },
+                    };
+            journal.record(row);
+        }
+        const observedTransaction = resolveAcceptedLifecycleTransaction({
+            read: replayed?.repository ?? (await observe(stableRoot, contractId)).repository,
+            transactionObjectId: result.ledgerHead,
+            expectedContract: contractId,
+        });
+        if (observedTransaction.status !== "accepted") {
+            throw new FlowError("COMMITTED_LEDGER_REREAD_FAILED", `accepted ledger transaction ${result.ledgerHead} could not be reread (${observedTransaction.reason})`);
+        }
+        committedResult = {
+            status: "committed",
+            head: result.ledgerHead,
+            transaction: observedTransaction,
+            carrier,
+            effects: journal.all(),
+            cancellationObserved: signal?.aborted ?? false,
+        };
+        return committedResult;
+    }
+    async function replayDerivedState() {
+        const observed = await observe(stableRoot, contractId);
+        currentLifecycle = observed.lifecycle;
+        const bind = acceptedBind(observed.lifecycle);
+        let committedTarget = observed.target;
+        let materialized = {
+            status: "failed",
+            ledgerHead: observed.lifecycle.observedLedgerHead,
+            cause: "carrier projection was not attempted",
+        };
+        await replayCommittedDerivedState({
+            cwd: stableRoot,
+            repository: observed.repository,
+            lifecycle: observed.lifecycle,
+            target: committedTarget,
+            journal,
+            adapters: {
+                reconcileActiveWorktree: async () => {
+                    committedTarget = await resolveContractCarrierTarget(stableRoot, contractId, bind);
+                    let created = false;
+                    if (committedTarget.status !== "available" && bind.data.workspace === "worktree") {
+                        const worktreePath = await contractWorktreePathFromBind(stableRoot, contractId, bind);
+                        try {
+                            await fs.access(worktreePath);
+                            throw Object.assign(new Error(`worktree path ${worktreePath} is occupied by an unowned filesystem entry`), { code: "BIND_WORKTREE_PATH_OCCUPIED", facts: { path: worktreePath, occupant: "unowned-filesystem-entry" } });
+                        }
+                        catch (error) {
+                            if (!(error instanceof Error) || !("code" in error) || error.code !== "ENOENT")
+                                throw error;
+                        }
+                        await defaultCreateWorktree({
+                            cwd: stableRoot,
+                            id: contractId,
+                            branch: `keiyaku/${contractId}`,
+                            base: bind.data.base,
+                            worktreePath,
+                        });
+                        committedTarget = await resolveContractCarrierTarget(stableRoot, contractId, bind);
+                        created = true;
+                    }
+                    if (committedTarget.status !== "available")
+                        throw new FlowError("CARRIER_TARGET_UNAVAILABLE", committedTarget.reason);
+                    const renewed = await reconcileFoldedDeliveryWorktree({ targetRoot: committedTarget.root, lifecycle: observed.lifecycle });
+                    return { status: created || renewed === "created" ? "created" : "already-present", target: committedTarget };
+                },
+                materializeContractView: async ({ lifecycle: accepted, target: acceptedTarget }) => {
+                    const projected = await convergeCarrier(stableRoot, contractId, observed.repository, accepted, acceptedTarget, contractViewWriter);
+                    materialized = projected;
+                    if (projected.status === "failed")
+                        throw new FlowError("CARRIER_MATERIALIZATION_FAILED", projected.cause);
+                    if (projected.status === "target-unavailable")
+                        throw new FlowError("CARRIER_TARGET_UNAVAILABLE", projected.reason);
+                    return projected.status === "current" ? "already-present" : "created";
+                },
+                retireContractView: async ({ lifecycle: accepted, target: acceptedTarget }) => {
+                    return retireTerminalHereCarrier(accepted, acceptedTarget);
+                },
+                replayClaimTarget: (landing) => replayClaimTargetWorktree(stableRoot, landing),
+                cleanupWorkspace: terminalWorkspaceCleanup ?? cleanupContractWorkspace,
+                observeDeliveryRef: observeTerminalDeliveryRef,
+            },
+        });
+        const carrierProjection = journal.all().find((row) => row.effect === "carrier-projection");
+        if (["claimed", "forfeited"].includes(observed.lifecycle.phase) && carrierProjection?.status === "succeeded") {
+            materialized = { status: "retired", ledgerHead: observed.lifecycle.observedLedgerHead, reason: "terminal" };
+        }
+        return materialized;
+    }
+    return {
+        mode,
+        stableRoot,
+        contractId,
+        lifecycle,
+        repository,
+        target,
+        initialCarrier,
+        pins,
+        journal,
+        async completeReplay(_carrierMode = "project") {
+            if (!committedResult)
+                throw new FlowError("INTERNAL_STATE", `contract ${contractId} has no committed mutation to replay`);
+            const materialized = await replayDerivedState();
+            committedResult = {
+                ...committedResult,
+                carrier: materialized,
+                effects: journal.all(),
+                cancellationObserved: effectsStarted && (signal?.aborted ?? false),
+            };
+            return materialized;
+        },
+        replayDerivedState,
+        async reread() {
+            if (!effectsStarted)
+                checkCancellation(signal);
+            const observed = await observe(stableRoot, contractId);
+            currentLifecycle = observed.lifecycle;
+            if (!effectsStarted)
+                checkCancellation(signal);
+            return { lifecycle: observed.lifecycle, repository: observed.repository, target: observed.target, pins: observed.pins };
+        },
+        async revalidate() {
+            if (!effectsStarted)
+                checkCancellation(signal);
+            const observed = await observe(stableRoot, contractId);
+            currentLifecycle = observed.lifecycle;
+            if (!effectsStarted)
+                checkCancellation(signal);
+            return { lifecycle: observed.lifecycle, repository: observed.repository, target: observed.target, pins: observed.pins };
+        },
+        beginEffects() {
+            if (!effectsStarted)
+                checkCancellation(signal);
+            effectsStarted = true;
+        },
+        effectsStarted() {
+            return effectsStarted;
+        },
+        cancellationObserved() {
+            return effectsStarted && (signal?.aborted ?? false);
+        },
+        committedResult() {
+            return committedResult;
+        },
+        async publishAuthoritative(transaction) {
+            if (authoritativeTransactionSelected)
+                throw new FlowError("INTERNAL_STATE", `carrier session ${contractId} already selected an authoritative transaction`);
+            authoritativeTransactionSelected = true;
+            if (transaction.entries.some((entry) => entry.contract !== contractId))
+                throw new FlowError("INTERNAL_STATE", `authoritative transaction does not belong to carrier session ${contractId}`);
+            if (transaction.admittedLedgerHead !== admittedLedgerHead)
+                throw new FlowError("CONCURRENT_MODIFICATION", `authoritative transaction ledger CAS does not match immutable carrier admission ${contractId}`);
+            if (transaction.acceptedLifecycleTail !== admittedLifecycleTail)
+                throw new FlowError("CONCURRENT_MODIFICATION", `authoritative transaction lifecycle tail does not match immutable carrier admission ${contractId}`);
+            const accepted = transaction.entries.at(-1);
+            const replaySteps = transaction.verb === "renew" && accepted.kind === "renew" && "delivery" in transaction
+                ? [{
+                        effect: "delivery-worktree-projection",
+                        dependencies: [],
+                        run: async () => (renewDeliveryProjector ?? projectRenewDeliveryWorktree)(target, transaction.delivery.expectedOid, accepted.data.newHead),
+                    }]
+                : [];
+            return publishRepository(transaction, replaySteps);
+        },
+        async replayCommitted(input) {
+            if (mode !== "mutation")
+                throw new FlowError("INTERNAL_STATE", `carrier ${mode} session cannot replay committed ledger facts`);
+            const observed = await observe(stableRoot, contractId);
+            const accepted = resolveAcceptedLifecycleTransaction({ read: observed.repository, transactionObjectId: input.transactionObjectId, expectedContract: contractId });
+            if (accepted.status !== "accepted")
+                throw new FlowError("CONCURRENT_MODIFICATION", `cannot replay unproved transaction ${input.transactionObjectId}`);
+            const renew = accepted.entries.find((entry) => entry.kind === "renew");
+            if (renew && (observed.lifecycle.pins.base !== renew.data.newBase || observed.lifecycle.pins.delivery !== renew.data.newHead || observed.pins.delivery.head !== renew.data.newHead || observed.pins.target.head !== renew.data.newBase)) {
+                throw new FlowError("CONCURRENT_MODIFICATION", `accepted renew transaction ${input.transactionObjectId} no longer matches current coordinates`);
+            }
+            currentLifecycle = observed.lifecycle;
+            return finalizeCommitted({
+                head: input.transactionObjectId,
+                ...(renew ? { renewProjection: { target: observed.target, oldHead: renew.data.oldHead, newHead: renew.data.newHead } } : {}),
+                carrier: input.carrier,
+            });
+        },
+    };
+}
+async function convergeCarrier(stableRoot, contractId, initialRepository, initialLifecycle, initialTarget, contractViewWriter) {
+    let repository = initialRepository;
+    let lifecycle = initialLifecycle;
+    let target = initialTarget;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        const published = await publishCarrier({ stableRoot, contractId, repository, lifecycle, target, contractViewWriter });
+        if (published.status !== "failed")
+            return published;
+        const activeHead = (await readRepositoryLifecycle(stableRoot)).observedLedgerHead;
+        if (activeHead === lifecycle.observedLedgerHead)
+            return published;
+        const observed = await observe(stableRoot, contractId);
+        repository = observed.repository;
+        lifecycle = observed.lifecycle;
+        target = observed.target;
+    }
+    return { status: "failed", ledgerHead: lifecycle.observedLedgerHead, ...(target.status === "available" ? { target: target.path } : {}), cause: "carrier convergence did not reach a stable ledger head" };
+}
+export async function convergeContractCarrier(input) {
+    return withContractCarrierSession({ ...input, mode: "observe-only" }, async (session) => ({ lifecycle: session.lifecycle, repository: session.repository, target: session.target, carrier: session.initialCarrier }));
+}
+/** Carrier surface step for the shared reconciler while it owns the carrier gate. */
+export async function reconcileContractCarrierProjection(input) {
+    checkCancellation(input.signal);
+    const stableRoot = await stableRepoRoot(input.cwd);
+    const observed = await observe(stableRoot, input.contractId);
+    const carrier = await convergeCarrier(stableRoot, input.contractId, observed.repository, observed.lifecycle, observed.target, input.contractViewWriter);
+    const reconciled = carrier.ledgerHead === observed.lifecycle.observedLedgerHead
+        ? observed
+        : await observe(stableRoot, input.contractId);
+    return {
+        lifecycle: reconciled.lifecycle,
+        repository: reconciled.repository,
+        target: reconciled.target,
+        carrier,
+    };
+}