@astrosheep/keiyaku 2.9.8 → 2.9.10

package/build/core/bind-reconciliation.js

@@ -0,0 +1,390 @@
+import { FlowError } from "../flow-error.js";
+import { access } from "node:fs/promises";
+import { lookupCurrentContract, readRepositoryLifecycle } from "./repository-ledger/read-model.js";
+import { withContractCarrierSession } from "./contract-carrier.js";
+import { stableRepoRoot, contractWorktreePathFromBind, findRegisteredContractWorktreePath } from "./worktree-path.js";
+import { defaultCreateWorktree } from "./bind-workspace.js";
+import { isCommissionId } from "./ids.js";
+import { REPOSITORY_LEDGER_REF, repositoryDeliveryRef } from "./repository-ledger/codec.js";
+import { resolveLocalBranchHead } from "../git/refs.js";
+import { runWorktreeBootstrap, bootstrapEntryDataFromObservation, isBootstrapSuccess } from "./worktree-bootstrap.js";
+import { committedLifecycleFacts, containedCommittedLifecycleFacts, EffectJournal } from "./outcome-base.js";
+export async function publishBindBootstrap(session, entry, expectedLedgerHead) {
+    return await session.publishAuthoritative({ verb: "bootstrap", admittedLedgerHead: expectedLedgerHead, acceptedLifecycleTail: session.lifecycle.history.at(-1).objectId, entries: [entry] });
+}
+export async function publishBindFailedForfeit(session, entry, delivery, expectedLedgerHead) {
+    return await session.publishAuthoritative({
+        verb: "forfeit",
+        admittedLedgerHead: expectedLedgerHead,
+        acceptedLifecycleTail: session.lifecycle.history.at(-1).objectId,
+        entries: [entry],
+        delivery: {
+            ref: repositoryDeliveryRef(entry.contract),
+            expectedOid: delivery.status === "present" ? delivery.head : null,
+        },
+    });
+}
+function copyAcceptedBindEntry(entry) {
+    const common = {
+        title: entry.data.title,
+        context: entry.data.context,
+        objective: entry.data.objective,
+        design: entry.data.design,
+        scope: [...entry.data.scope],
+        criteria: [...entry.data.criteria],
+        verification: [...entry.data.verification],
+        extensions: entry.data.extensions.map((extension) => ({ title: extension.title, content: extension.content })),
+        base: entry.data.base,
+        target: entry.data.target,
+        ...(entry.data.after ? { after: [...entry.data.after] } : {}),
+        ...(entry.data.taskIds ? { taskIds: [...entry.data.taskIds] } : {}),
+    };
+    return {
+        v: 2,
+        kind: "bind",
+        contract: entry.contract,
+        at: entry.at,
+        actor: entry.actor,
+        data: entry.data.workspace === "worktree"
+            ? {
+                ...common,
+                workspace: "worktree",
+                place: entry.data.place,
+                ...(entry.data.bootstrap ? { bootstrap: { command: [...entry.data.bootstrap.command], timeoutMs: entry.data.bootstrap.timeoutMs } } : {}),
+            }
+            : { ...common, workspace: "here" },
+    };
+}
+function copyAcceptedBootstrapEntry(entry) {
+    return {
+        v: 1,
+        kind: "bootstrap",
+        contract: entry.contract,
+        at: entry.at,
+        actor: entry.actor,
+        data: {
+            result: { ...entry.data.result },
+            durationMs: entry.data.durationMs,
+            ...(entry.data.stderrTail === undefined ? {} : { stderrTail: entry.data.stderrTail }),
+            ...(entry.data.stderrTruncated === undefined ? {} : { stderrTruncated: entry.data.stderrTruncated }),
+        },
+    };
+}
+function bootstrapProgressLine(command) {
+    return `bootstrap » ${command.join(" ")}`;
+}
+function workspaceBindView(entry) {
+    return entry;
+}
+export async function revalidateBindAuthority(input) {
+    const [target, delivery] = await Promise.all([
+        resolveLocalBranchHead(input.cwd, input.target),
+        resolveLocalBranchHead(input.cwd, input.deliveryRef),
+    ]);
+    if (target?.head !== input.targetHead) {
+        throw new FlowError("CONCURRENT_MODIFICATION", `bind target changed from ${input.targetHead}`);
+    }
+    if (delivery !== null) {
+        throw new FlowError("CONCURRENT_MODIFICATION", `bind delivery ref already exists: ${input.deliveryRef}`);
+    }
+}
+export function committedOrThrow(result, operation) {
+    if (result.family === "committed")
+        return result;
+    const detail = `${result.code}: ${result.cause}`;
+    if (result.family === "indeterminate") {
+        throw new FlowError("INTERNAL_STATE", `${operation}_INDETERMINATE: ${detail}`);
+    }
+    throw new FlowError("CONCURRENT_MODIFICATION", `${operation}_REFUSED: ${detail}`);
+}
+function effectCause(row) {
+    return row.status === "succeeded" ? undefined : row.cause;
+}
+function bindResult(input) {
+    const ledgerHead = input.heads.bindFailedForfeit ?? input.heads.bootstrap ?? input.heads.bind;
+    const reconciliationKey = `${input.coordinates.id}:${input.heads.bind}`;
+    if (input.cause) {
+        return {
+            ledgerHead,
+            heads: input.heads,
+            reconciliationKey,
+            ...containedCommittedLifecycleFacts({
+                head: ledgerHead,
+                entryKind: input.heads.bindFailedForfeit ? "forfeit" : input.heads.bootstrap ? "bootstrap" : "bind",
+                contractId: input.coordinates.id,
+                carrier: input.carrier,
+                cause: input.cause,
+                prerequisites: input.journal.rows("prerequisite"),
+                downstream: input.journal.rows("downstream"),
+            }),
+            replay: {
+                idempotencyKey: reconciliationKey,
+                action: "reconcile",
+                reason: "one or more committed-head effects remain",
+            },
+        };
+    }
+    const lifecycle = committedLifecycleFacts({
+        head: ledgerHead,
+        entryKind: input.heads.bootstrap ? "bootstrap" : "bind",
+        contractId: input.coordinates.id,
+        carrier: input.carrier,
+        prerequisites: input.journal.rows("prerequisite"),
+        downstream: input.journal.rows("downstream"),
+    });
+    return {
+        ...input.coordinates,
+        ledgerHead,
+        heads: input.heads,
+        reconciliationKey,
+        surfaces: bindSurfaceReceipts(input.journal),
+        ...lifecycle,
+        replay: { ...lifecycle.replay, idempotencyKey: reconciliationKey },
+    };
+}
+function bindSurfaceReceipts(journal) {
+    const mapping = new Map([
+        ["task-board-projection", "task-view"],
+        ["registry-projection", "registry"],
+        ["worktree-projection", "worktree"],
+        ["bootstrap-execution", "bootstrap"],
+        ["carrier-projection", "carrier"],
+    ]);
+    const receipts = [];
+    for (const row of journal.rows("downstream")) {
+        const surface = mapping.get(row.effect);
+        if (!surface || row.status !== "succeeded")
+            continue;
+        const raw = row.receipt?.status;
+        const status = raw === "current" || raw === "already-present" || raw === "not-applicable"
+            ? "already-present"
+            : "created";
+        receipts.push({ surface, status });
+    }
+    return receipts;
+}
+/**
+ * Sole replay-only entry for a committed bind. It never allocates identity or
+ * reads draft input; every coordinate is reconstructed from the accepted bind.
+ */
+export async function reconcileCommittedBind(input, admittedScopeOverlaps) {
+    if (input.signal?.aborted) {
+        throw new FlowError("CARRIER_GATE_CANCELLED", "contract replay cancelled before derived effects");
+    }
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const result = await withContractCarrierSession({
+            cwd: input.cwd,
+            contractId: input.contractId,
+            mode: "mutation",
+            signal: input.signal,
+            ...(input.terminalWorkspaceCleanup ? { terminalWorkspaceCleanup: input.terminalWorkspaceCleanup } : {}),
+        }, async (session) => reconcileBindContractLocked({ ...input, cwd: session.stableRoot }, session, admittedScopeOverlaps));
+        if ("continueAfterFailedBootstrap" in result)
+            continue;
+        return result;
+    }
+    throw new FlowError("INTERNAL_STATE", `bind-failed finalization for ${input.contractId} did not settle after bootstrap re-admission`);
+}
+async function reconcileBindContractLocked(input, replaySession, admittedScopeOverlaps) {
+    const stableRoot = await stableRepoRoot(input.cwd);
+    if (!isCommissionId(input.contractId)) {
+        throw new FlowError("INVALID_TARGET", `bind replay requires a full canonical contract id; got ${input.contractId}`);
+    }
+    const initialRead = await readRepositoryLifecycle(stableRoot);
+    const outcome = lookupCurrentContract(initialRead, input.contractId);
+    if (outcome.status === "absent")
+        throw new FlowError("CONTRACT_NOT_FOUND", `contract ${input.contractId} not found`);
+    if (outcome.status !== "healthy") {
+        throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} is unavailable (${outcome.status})`);
+    }
+    const bindRow = outcome.model.history.find((row) => row.entry.kind === "bind");
+    if (!bindRow || bindRow.entry.kind !== "bind")
+        throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} has no accepted bind`);
+    const bootstrapRow = outcome.model.history.find((row) => row.entry.kind === "bootstrap");
+    const forfeitRow = outcome.model.history.find((row) => row.entry.kind === "forfeit");
+    const replayingBindFailedTerminal = outcome.model.phase === "forfeited"
+        && bootstrapRow?.entry.kind === "bootstrap"
+        && !isBootstrapSuccess(bootstrapRow.entry.data)
+        && forfeitRow?.entry.kind === "forfeit"
+        && forfeitRow.entry.data.reason === "bind-failed";
+    if (["claimed", "forfeited"].includes(outcome.model.phase) && !replayingBindFailedTerminal) {
+        throw new FlowError("CONTRACT_TERMINAL", `contract ${input.contractId} is terminal (${outcome.model.phase})`);
+    }
+    const entry = copyAcceptedBindEntry(bindRow.entry);
+    const workspace = entry.data.workspace;
+    const branch = `keiyaku/${entry.contract}`;
+    const worktreePath = await contractWorktreePathFromBind(stableRoot, entry.contract, workspaceBindView(entry));
+    const targetRoot = workspace === "here" ? stableRoot : worktreePath;
+    const deps = input.dependencies ?? {};
+    const heads = {
+        bind: bindRow.objectId,
+        bootstrap: bootstrapRow?.objectId ?? null,
+        bindFailedForfeit: replayingBindFailedTerminal ? forfeitRow.objectId : null,
+    };
+    const journal = new EffectJournal(`bind:${entry.contract}:${bindRow.objectId}`);
+    journal.record({
+        effect: "ledger-cas",
+        idempotencyKey: `bind:${entry.contract}:${bindRow.objectId}:ledger-cas`,
+        status: "succeeded",
+        receipt: { bindHead: bindRow.objectId, observed: true },
+    });
+    let containedCause;
+    const rememberFailure = (row) => { containedCause ??= effectCause(row); };
+    const scopeOverlaps = [...admittedScopeOverlaps];
+    const bootstrapPlan = entry.data.workspace === "worktree" ? entry.data.bootstrap : undefined;
+    if (!replayingBindFailedTerminal && bootstrapPlan) {
+        const worktreeReplay = await journal.run({
+            effect: "bootstrap-worktree-prerequisite",
+            run: async () => {
+                const registered = await findRegisteredContractWorktreePath(stableRoot, entry.contract);
+                if (registered === worktreePath)
+                    return { status: "already-present", path: worktreePath };
+                try {
+                    await 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 (input.createWorktree ?? defaultCreateWorktree)({ cwd: stableRoot, id: entry.contract, branch, base: entry.data.base, worktreePath });
+                return { status: "created", path: worktreePath };
+            },
+        });
+        rememberFailure(worktreeReplay);
+    }
+    let bootstrapData = bootstrapRow?.entry.kind === "bootstrap"
+        ? copyAcceptedBootstrapEntry(bootstrapRow.entry)
+        : undefined;
+    let publishedFailedBootstrapThroughSession = false;
+    if (bootstrapPlan) {
+        const locked = lookupCurrentContract(await readRepositoryLifecycle(stableRoot), entry.contract);
+        if (locked.status !== "healthy")
+            throw new FlowError("INTERNAL_STATE", `contract ${entry.contract} became unavailable during bootstrap replay`);
+        const existingBootstrap = locked.model.history.find((row) => row.entry.kind === "bootstrap")?.entry;
+        bootstrapData = existingBootstrap?.kind === "bootstrap"
+            ? copyAcceptedBootstrapEntry(existingBootstrap)
+            : undefined;
+        if (bootstrapData) {
+            const row = await journal.run({ effect: "bootstrap-execution", run: async () => ({ status: "already-present" }) });
+            rememberFailure(row);
+            const publication = await journal.run({
+                effect: "bootstrap-ledger-cas",
+                dependency: "bootstrap-execution",
+                run: async () => ({ head: heads.bootstrap, status: "already-present" }),
+            });
+            rememberFailure(publication);
+        }
+        else {
+            const execution = await journal.run({
+                effect: "bootstrap-execution",
+                dependency: "bootstrap-worktree-prerequisite",
+                run: async () => {
+                    input.onProgress?.(bootstrapProgressLine(bootstrapPlan.command));
+                    const observation = await (input.bootstrapRunner ?? runWorktreeBootstrap)({ cwd: worktreePath, plan: bootstrapPlan }, input.bootstrapDependencies);
+                    const data = bootstrapEntryDataFromObservation(observation);
+                    bootstrapData = { v: 1, kind: "bootstrap", contract: entry.contract, at: new Date(input.nowMs).toISOString(), actor: input.actor, data };
+                    return { status: "created", result: data.result.kind };
+                },
+            });
+            rememberFailure(execution);
+            const publication = await journal.run({
+                effect: "bootstrap-ledger-cas",
+                dependency: "bootstrap-execution",
+                run: async () => {
+                    const current = await readRepositoryLifecycle(stableRoot);
+                    const written = deps.publishBootstrap
+                        ? await deps.publishBootstrap(bootstrapData, current.observedLedgerHead)
+                        : await publishBindBootstrap(replaySession, bootstrapData, current.observedLedgerHead);
+                    if (written.status !== "committed")
+                        throw new FlowError("CONCURRENT_MODIFICATION", "BIND_BOOTSTRAP_TRANSACTION_REFUSED");
+                    publishedFailedBootstrapThroughSession = !deps.publishBootstrap && !isBootstrapSuccess(bootstrapData.data);
+                    heads.bootstrap = written.head;
+                    return { head: written.head };
+                },
+            });
+            rememberFailure(publication);
+        }
+    }
+    const bootstrapEntry = bootstrapData?.kind === "bootstrap" ? bootstrapData : undefined;
+    if (publishedFailedBootstrapThroughSession)
+        return { continueAfterFailedBootstrap: true };
+    if (bootstrapEntry && !isBootstrapSuccess(bootstrapEntry.data)) {
+        const forfeitPublication = await journal.run({
+            effect: "bind-failed-forfeit-cas",
+            dependency: heads.bootstrap ? "bootstrap-ledger-cas" : undefined,
+            run: async () => {
+                const current = await readRepositoryLifecycle(stableRoot);
+                const currentContract = lookupCurrentContract(current, entry.contract);
+                if (currentContract.status === "healthy" && currentContract.model.phase === "forfeited") {
+                    const existing = currentContract.model.history.find((row) => row.entry.kind === "forfeit");
+                    if (!existing)
+                        throw new FlowError("INTERNAL_STATE", `forfeited contract ${entry.contract} has no accepted terminal entry`);
+                    heads.bindFailedForfeit = existing.objectId;
+                    return { head: existing.objectId, status: "already-present" };
+                }
+                const delivery = await resolveLocalBranchHead(stableRoot, repositoryDeliveryRef(entry.contract));
+                if (!delivery) {
+                    throw new FlowError("INTERNAL_STATE", `contract ${entry.contract} delivery ref is absent before bind-failed forfeit`);
+                }
+                const forfeitEntry = {
+                    v: 2,
+                    kind: "forfeit",
+                    contract: entry.contract,
+                    at: new Date(input.nowMs).toISOString(),
+                    actor: input.actor,
+                    data: { reason: "bind-failed", actor: input.actor, finalHead: delivery.head },
+                };
+                const deliveryState = { status: "present", head: delivery.head };
+                const written = deps.publishBindFailedForfeit
+                    ? await deps.publishBindFailedForfeit(forfeitEntry, deliveryState, current.observedLedgerHead)
+                    : await publishBindFailedForfeit(replaySession, forfeitEntry, deliveryState, current.observedLedgerHead);
+                if (written.status !== "committed")
+                    throw new FlowError("CONCURRENT_MODIFICATION", "BIND_FAILED_FORFEIT_TRANSACTION_REFUSED");
+                heads.bindFailedForfeit = written.head;
+                return { head: written.head, status: "created" };
+            },
+        });
+        rememberFailure(forfeitPublication);
+        const terminalCarrier = await replaySession.replayDerivedState();
+        for (const row of replaySession.journal.all()) {
+            journal.record(row);
+            rememberFailure(row);
+        }
+        return bindResult({
+            coordinates: {
+                id: entry.contract, ref: REPOSITORY_LEDGER_REF, target: entry.data.target,
+                place: workspace === "worktree" ? entry.data.place : null,
+                ...(workspace === "worktree" ? { branch } : {}), worktreePath: targetRoot,
+                workspace, scopeOverlaps,
+            },
+            heads,
+            journal,
+            carrier: terminalCarrier,
+            cause: { code: "BIND_BOOTSTRAP_FAILED", message: `worktree bootstrap failed with ${bootstrapEntry.data.result.kind}` },
+        });
+    }
+    const carrier = await replaySession.replayDerivedState();
+    for (const row of replaySession.journal.all()) {
+        journal.record(row);
+        rememberFailure(row);
+    }
+    return bindResult({
+        coordinates: {
+            id: entry.contract, ref: REPOSITORY_LEDGER_REF, target: entry.data.target,
+            place: workspace === "worktree" ? entry.data.place : null,
+            ...(workspace === "worktree" ? { branch } : {}), worktreePath: targetRoot,
+            workspace, scopeOverlaps,
+        },
+        heads,
+        journal,
+        carrier,
+        ...(containedCause ? { cause: containedCause } : {}),
+    });
+}
+export async function reconcileBindContract(input) {
+    return await reconcileCommittedBind(input, []);
+}

package/build/core/bind-workspace.js

@@ -1,12 +1,8 @@
 import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import { KEIYAKU_FILE } from "../keiyaku.js";
 import { createGit, wrapGitError } from "../git/core.js";
-import { listContractIds, readLedger } from "./ledger.js";
 import { CONTRACT_PLACES } from "./places.js";
-import { renderContractView } from "./contract-view.js";
-import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
-import { contractWorktreePathFromBind, findBindEntry } from "./worktree-path.js";
+import { lookupCurrentContract, readRepositoryLifecycle } from "./repository-ledger/read-model.js";
+import { contractWorktreePathFromBind } from "./worktree-path.js";
 export async function createContractBranch(cwd, branch, base) {
     const git = createGit(cwd);
     try {
@@ -80,21 +76,14 @@ export async function cleanupCreatedBindResources(cwd, resources) {
     }
     return failures;
 }
-export async function materializeContractView(input) {
-    const keiyakuPath = path.join(input.targetRoot, KEIYAKU_FILE);
-    await fs.mkdir(path.dirname(keiyakuPath), { recursive: true });
-    await fs.writeFile(keiyakuPath, renderContractView({ id: input.id, entries: input.entries }), "utf8");
-    return keiyakuPath;
-}
-async function occupiedWorktreePlaces(cwd) {
+function occupiedWorktreePlaces(read) {
     const occupied = new Set();
-    for (const id of await listContractIds(cwd)) {
-        const ledger = await readLedger(cwd, id);
-        if (!ledger || isTerminalState(deriveContractState(ledger.entries)))
+    for (const model of read.contracts) {
+        if (lookupCurrentContract(read, model.contract).status !== "healthy")
             continue;
-        const place = findBindEntry(ledger.entries)?.data.place;
-        if (place)
-            occupied.add(place);
+        const worktree = model.resources.worktree;
+        if (worktree?.state === "held")
+            occupied.add(worktree.place);
     }
     return occupied;
 }
@@ -113,7 +102,10 @@ function nextGenerationPlace(base, occupied) {
     }
 }
 export async function allocateWorktreePlace(cwd, randomBytes) {
-    const occupied = await occupiedWorktreePlaces(cwd);
+    return allocateWorktreePlaceFromRead(await readRepositoryLifecycle(cwd), randomBytes);
+}
+export function allocateWorktreePlaceFromRead(read, randomBytes) {
+    const occupied = occupiedWorktreePlaces(read);
     const candidates = CONTRACT_PLACES.filter((place) => !occupied.has(place));
     if (candidates.length > 0) {
         return candidates[randomIndex(randomBytes, candidates.length)];