@astrosheep/keiyaku 2.9.13 → 4.0.0

package/build/core/bind.js

@@ -1,503 +0,0 @@
-import * as crypto from "node:crypto";
-import { readdir } from "node:fs/promises";
-import * as path from "node:path";
-import { assertSettingsKnobUsable } from "../config/settings/disease.js";
-import { loadKeiyakuSettings } from "../config/settings/loader.js";
-import { FlowError } from "../flow-error.js";
-import { advanceRepositorySnapshotWithBind, lookupCurrentContract, readRepositoryLifecycle, } from "./repository-ledger/read-model.js";
-import { REPOSITORY_LEDGER_REF, repositoryDeliveryRef, } from "./repository-ledger/codec.js";
-import { publishBindTransaction, } from "./repository-ledger/write-transaction.js";
-import { bindEffectiveScope } from "./repository-ledger/fold.js";
-import { activeWorkspaceHereContracts } from "./repository-ledger/inventory.js";
-import { repositoryLedgerHead } from "./repository-ledger/identity.js";
-import { describeMissingBindSections, materializeBindDraft, mergeBindDraft, missingBindDraftSections, parseBindDraft, parsePartialBindDraft, renderBindDraft, renderMissingBindSectionsTemplate, } from "./draft.js";
-import { buildContractId, isCommissionId } from "./ids.js";
-import { admitScopeRegistration, } from "./registry.js";
-import { normalizeTargetRef } from "./target-ref.js";
-import { previewTaskBoardForBind, withPreparedTaskBindSnapshot, } from "./task/index.js";
-import { stableRepoRoot } from "./worktree-path.js";
-import { allocateWorktreePlaceFromRead, } from "./bind-workspace.js";
-import { committedOrThrow, reconcileBindContract, reconcileCommittedBindFromSnapshot, requiresBindRecovery } from "./bind-reconciliation.js";
-import { allocateTaskNamespace, taskNamespaceFromScope, taskNamespaceScope } from "./task/coordinate.js";
-import { resolveExactRefHeads } from "../git/refs.js";
-import { runGitProcess } from "../git/core.js";
-export { reconcileBindContract } from "./bind-reconciliation.js";
-function randomBytesDefault() {
-    return [...crypto.randomBytes(10)];
-}
-function resolvedBootstrapPlan(settings) {
-    if (!settings)
-        return undefined;
-    return {
-        command: [...settings.command],
-        timeoutMs: settings.timeoutMs,
-    };
-}
-async function readPersistedTaskNamespaces(stableRoot) {
-    try {
-        const entries = await readdir(path.join(stableRoot, ".keiyaku", "tasks"), { withFileTypes: true });
-        return new Set(entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name));
-    }
-    catch (error) {
-        if (error instanceof Error && "code" in error && error.code === "ENOENT")
-            return new Set();
-        throw error;
-    }
-}
-async function observeBindRefs(stableRoot, defaultBranchOverride) {
-    const branches = defaultBranchOverride ? [defaultBranchOverride] : ["main", "master"];
-    const refs = [REPOSITORY_LEDGER_REF, ...branches.map((branch) => normalizeTargetRef(branch))];
-    const heads = await resolveExactRefHeads(stableRoot, refs);
-    const selected = branches.find((branch) => heads.get(normalizeTargetRef(branch)) !== null);
-    return {
-        ledgerHead: heads.get(REPOSITORY_LEDGER_REF) ?? null,
-        branch: selected ? { branch: selected, head: heads.get(normalizeTargetRef(selected)) } : null,
-    };
-}
-function bindDraftWithTaskNamespace(draft, read, persistedNamespaces) {
-    const declared = draft.scope.flatMap((term) => {
-        const namespace = taskNamespaceFromScope(term);
-        return namespace ? [namespace] : [];
-    });
-    if (declared.length > 1)
-        throw new FlowError("INVALID_TARGET", "bind scope must carry exactly one contract task namespace");
-    const occupied = new Set(read.contracts.flatMap((contract) => contract.effectiveScope.flatMap((term) => {
-        const namespace = taskNamespaceFromScope(term);
-        return namespace ? [namespace] : [];
-    })));
-    for (const namespace of persistedNamespaces)
-        occupied.add(namespace);
-    if (declared.length === 1) {
-        if (occupied.has(declared[0]))
-            throw new FlowError("INVALID_TARGET", `task namespace ${declared[0]} is already occupied`);
-        return draft;
-    }
-    const namespace = allocateTaskNamespace(draft.title, occupied);
-    return { ...draft, scope: [...draft.scope, taskNamespaceScope(namespace)] };
-}
-function makeBindEntry(input) {
-    const common = {
-        title: input.draft.title,
-        context: input.draft.context,
-        objective: input.draft.objective,
-        design: input.draft.design,
-        scope: input.draft.scope,
-        criteria: input.draft.criteria,
-        verification: input.draft.verification,
-        extensions: input.draft.extensions,
-        base: input.base,
-        target: input.target,
-        ...(input.after.length > 0 ? { after: input.after } : {}),
-        ...(input.taskIds ? { taskIds: [...input.taskIds] } : {}),
-    };
-    return {
-        v: 3,
-        kind: "bind",
-        contract: input.id,
-        at: input.at,
-        actor: input.actor,
-        data: input.workspace === "worktree"
-            ? { ...common, workspace: "worktree", place: input.place, ...(input.bootstrap ? { bootstrap: input.bootstrap } : {}) }
-            : { ...common, workspace: "here" },
-    };
-}
-function taskBindDefaults(task) {
-    const defaults = { title: task.title };
-    const objective = task.body.trim();
-    if (objective.length > 0)
-        defaults.objective = objective;
-    return defaults;
-}
-function incompleteTaskBindError(taskId, missing) {
-    const coordinate = taskId;
-    const template = renderMissingBindSectionsTemplate(missing);
-    const message = [
-        `task ${coordinate} carries no ${describeMissingBindSections(missing)}`,
-        `» keiyaku bind --task ${coordinate} - <<'KEIYAKU'`,
-        template,
-        "KEIYAKU",
-    ].join("\n");
-    return new FlowError("BIND_TASK_INCOMPLETE", message);
-}
-/**
- * Section-level merge for `bind --task`: task title/body are title/objective
- * defaults; stdin partial markdown sections override. Missing required sections
- * fail with a paste-ready partial heredoc template.
- */
-export function composeTaskBindDraft(input) {
-    const merged = mergeBindDraft(taskBindDefaults(input.task), parsePartialBindDraft(input.draft));
-    const missing = missingBindDraftSections(merged);
-    if (missing.length > 0) {
-        throw incompleteTaskBindError(input.task.id, missing);
-    }
-    return materializeBindDraft(merged);
-}
-function validateBindAfter(read, after) {
-    for (const contractId of after) {
-        if (!isCommissionId(contractId)) {
-            throw new FlowError("INVALID_TARGET", `after contract ${contractId} is not a valid contract id`);
-        }
-        const outcome = lookupCurrentContract(read, contractId);
-        if (outcome.status !== "healthy") {
-            throw new FlowError("INVALID_TARGET", `after contract ${contractId} is not a healthy existing contract`);
-        }
-    }
-}
-function canonicalBindAfter(explicit, selected = []) {
-    return [...new Set([
-            ...explicit,
-            ...selected.flatMap((task) => task.needs.flatMap((need) => need.contractId === undefined ? [] : [need.contractId])),
-        ])];
-}
-function assertContractAbsent(read, contractId) {
-    const outcome = lookupCurrentContract(read, contractId);
-    if (outcome.status === "absent")
-        return;
-    if (outcome.status === "indeterminate") {
-        throw new FlowError("INTERNAL_STATE", `BIND_ADMISSION_INDETERMINATE: cannot prove contract ${contractId} absent`);
-    }
-    throw new FlowError("CONCURRENT_MODIFICATION", `CONTRACT_ID_COLLISION: contract ${contractId} already exists`);
-}
-function admitWorkspaceOccupancy(read, workspace) {
-    if (workspace === "worktree")
-        return;
-    const occupants = activeWorkspaceHereContracts(read);
-    if (occupants.length === 0)
-        return;
-    throw new FlowError("INVALID_TARGET", `workspace here is occupied by nonterminal contract ${occupants.join(", ")}`);
-}
-/**
- * The common read-only bind admission candidate. Mutation uses this candidate
- * before task settlement; preview stops after it has observed all admission
- * facts and rendered the canonical draft.
- */
-async function admitBindCandidate(input, draft, read) {
-    draft = bindDraftWithTaskNamespace(draft, read, await readPersistedTaskNamespaces(input.cwd));
-    admitWorkspaceOccupancy(read, input.workspace);
-    const id = buildContractId({ title: draft.title, nowMs: input.nowMs, randomBytes: input.randomBytes });
-    assertContractAbsent(read, id);
-    validateBindAfter(read, input.after);
-    const provisionalEntry = makeBindEntry({
-        id,
-        at: new Date(input.nowMs).toISOString(),
-        actor: input.actor,
-        draft,
-        // Preview never writes the task-board commit. The current target head is
-        // sufficient for its read-only provisional entry and worktree coordinate.
-        base: input.base,
-        target: input.target,
-        after: input.after,
-        workspace: input.workspace,
-        place: input.place,
-        bootstrap: input.bootstrapPlan,
-        taskIds: input.taskIds ? [...input.taskIds] : undefined,
-    });
-    const scopeOverlaps = await admitScopeRegistration(input.cwd, {
-        contractId: id,
-        scope: bindEffectiveScope(provisionalEntry),
-        tree: input.base,
-        exclusive: input.exclusive,
-    }, read);
-    return {
-        id,
-        draft,
-        canonicalDraft: renderBindDraft(draft),
-        target: input.target,
-        place: input.workspace === "worktree" ? input.place ?? null : null,
-        workspace: input.workspace,
-        after: input.after,
-        scopeOverlaps,
-    };
-}
-export async function previewBindContract(input) {
-    const isTaskBound = input.taskIds !== undefined && input.taskIds.length > 0;
-    const ordinaryDraft = !isTaskBound ? parseBindDraft(input.draft) : undefined;
-    const workspace = input.workspace ?? "here";
-    const loadedSettings = await loadKeiyakuSettings(input.cwd);
-    assertSettingsKnobUsable(loadedSettings, "defaultBranch");
-    const observed = await observeBindRefs(input.cwd, loadedSettings.knobs?.defaultBranch);
-    const defaultBranch = observed.branch;
-    if (!defaultBranch) {
-        throw new FlowError("INTERNAL_STATE", "cannot bind: no default branch");
-    }
-    const target = normalizeTargetRef(defaultBranch.branch);
-    let bootstrapPlan;
-    if (workspace === "worktree") {
-        assertSettingsKnobUsable(loadedSettings, "worktreeBootstrap");
-        bootstrapPlan = resolvedBootstrapPlan(loadedSettings.knobs?.worktreeBootstrap);
-    }
-    const read = await readRepositoryLifecycle(input.cwd, { observedHead: observed.ledgerHead, signal: input.signal });
-    const randomBytes = input.randomBytes?.(0) ?? randomBytesDefault();
-    const place = workspace === "worktree" ? allocateWorktreePlaceFromRead(read, randomBytes) : undefined;
-    const taskAdmission = isTaskBound
-        ? await previewTaskBoardForBind({ cwd: input.cwd, taskIds: input.taskIds })
-        : { tasks: [] };
-    const draft = isTaskBound
-        ? composeTaskBindDraft({ task: taskAdmission.tasks[0], draft: input.draft })
-        : ordinaryDraft;
-    return await admitBindCandidate({
-        cwd: input.cwd,
-        actor: input.actor,
-        nowMs: input.nowMs,
-        after: input.after ?? [],
-        exclusive: input.exclusive,
-        workspace,
-        randomBytes,
-        base: defaultBranch.head,
-        target,
-        bootstrapPlan,
-        place,
-        ...(isTaskBound ? { taskIds: input.taskIds } : {}),
-    }, draft, read);
-}
-export async function bindContract(input) {
-    const stableRoot = await stableRepoRoot(input.cwd);
-    const isTaskBound = input.taskIds !== undefined && input.taskIds.length > 0;
-    const ordinaryDraft = !isTaskBound ? parseBindDraft(input.draft) : undefined;
-    const workspace = input.workspace ?? "here";
-    const at = new Date(input.nowMs).toISOString();
-    const after = input.after ?? [];
-    const publishBind = input.dependencies?.publishBind ?? publishBindTransaction;
-    const persistedTaskNamespaces = await readPersistedTaskNamespaces(stableRoot);
-    const loadedSettings = await loadKeiyakuSettings(stableRoot);
-    assertSettingsKnobUsable(loadedSettings, "defaultBranch");
-    let bootstrapPlan;
-    if (workspace === "worktree") {
-        assertSettingsKnobUsable(loadedSettings, "worktreeBootstrap");
-        bootstrapPlan = resolvedBootstrapPlan(loadedSettings.knobs?.worktreeBootstrap);
-    }
-    const observeEntry = async () => {
-        const attemptedReplay = new Map();
-        for (;;) {
-            const observed = await observeBindRefs(stableRoot, loadedSettings.knobs?.defaultBranch);
-            if (!observed.branch) {
-                if (loadedSettings.knobs?.defaultBranch)
-                    throw new FlowError("INVALID_SETTINGS", `configured defaultBranch '${loadedSettings.knobs.defaultBranch}' does not resolve`);
-                throw new FlowError("INTERNAL_STATE", "cannot bind: no default branch");
-            }
-            const read = await readRepositoryLifecycle(stableRoot, { observedHead: observed.ledgerHead, signal: input.signal });
-            const outstanding = read.contracts.filter(requiresBindRecovery);
-            if (outstanding.length === 0)
-                return { branch: observed.branch, read };
-            for (const lifecycle of outstanding) {
-                const priorAttempt = attemptedReplay.get(lifecycle.contract);
-                if (priorAttempt) {
-                    if (priorAttempt.completion.status === "contained") {
-                        const cause = priorAttempt.completion.cause;
-                        const code = cause.code === "BIND_WORKTREE_PATH_OCCUPIED"
-                            || cause.code === "CARRIER_MATERIALIZATION_FAILED"
-                            || cause.code === "CARRIER_TARGET_UNAVAILABLE"
-                            ? cause.code
-                            : "INTERNAL_STATE";
-                        throw new FlowError(code, cause.message);
-                    }
-                    throw new FlowError("INTERNAL_STATE", `bind entry replay for ${lifecycle.contract} completed without advancing its pending lifecycle state`);
-                }
-                attemptedReplay.set(lifecycle.contract, await reconcileBindContract({
-                    cwd: stableRoot,
-                    contractId: lifecycle.contract,
-                    actor: input.actor,
-                    nowMs: input.nowMs,
-                    ...(input.signal ? { signal: input.signal } : {}),
-                    ...(input.createWorktree ? { createWorktree: input.createWorktree } : {}),
-                    ...(input.onProgress ? { onProgress: input.onProgress } : {}),
-                    ...(input.bootstrapRunner ? { bootstrapRunner: input.bootstrapRunner } : {}),
-                    ...(input.bootstrapDependencies ? { bootstrapDependencies: input.bootstrapDependencies } : {}),
-                    dependencies: input.dependencies,
-                }));
-            }
-        }
-    };
-    let selectedDraft;
-    let selectedPlace;
-    let selectedId;
-    const selectCandidate = async (draft, read) => {
-        admitWorkspaceOccupancy(read, workspace);
-        const collided = [];
-        for (let attempt = 0; attempt < 2; attempt += 1) {
-            const randomBytes = input.randomBytes?.(attempt) ?? randomBytesDefault();
-            const place = workspace === "worktree" ? allocateWorktreePlaceFromRead(read, randomBytes) : undefined;
-            const id = buildContractId({ title: draft.title, nowMs: input.nowMs, randomBytes });
-            const outcome = lookupCurrentContract(read, id);
-            if (outcome.status === "indeterminate")
-                assertContractAbsent(read, id);
-            if (outcome.status !== "absent") {
-                collided.push(id);
-                continue;
-            }
-            selectedDraft = bindDraftWithTaskNamespace(draft, read, persistedTaskNamespaces);
-            selectedPlace = place;
-            selectedId = id;
-            return { contractId: id, at };
-        }
-        throw new FlowError("CONCURRENT_MODIFICATION", `CONTRACT_ID_COLLISION: contract id collision after two attempts: ${collided.join(", ")}`);
-    };
-    let entry;
-    let admittedScopeOverlaps = [];
-    let preparedTask;
-    let preparedTaskProjectionSucceeded = false;
-    let committedHead;
-    let committedEntryObjectId;
-    let admittedRead;
-    if (isTaskBound) {
-        let settled;
-        for (let attempt = 0; attempt < 4; attempt += 1) {
-            let lockedRead;
-            let target;
-            const attempted = await withPreparedTaskBindSnapshot({
-                location: { mode: "git", root: stableRoot, surfaceRoot: stableRoot, gitDir: path.join(stableRoot, ".git") },
-                observeBoard: async () => {
-                    const observed = await observeEntry();
-                    target = normalizeTargetRef(observed.branch.branch);
-                    lockedRead = observed.read;
-                    admittedRead = lockedRead;
-                    return { ref: target, head: observed.branch.head };
-                },
-                taskIds: input.taskIds,
-                signal: input.signal,
-                prepare: async (tasks) => {
-                    return await selectCandidate(composeTaskBindDraft({ task: tasks[0], draft: input.draft }), lockedRead);
-                },
-                transact: async (prepared, taskTransaction) => {
-                    if (prepared.boardRef !== target) {
-                        throw new FlowError("CONCURRENT_MODIFICATION", "locked task-board ref does not match the selected bind target");
-                    }
-                    admitWorkspaceOccupancy(lockedRead, workspace);
-                    const canonicalAfter = canonicalBindAfter(after, prepared.selected);
-                    validateBindAfter(lockedRead, canonicalAfter);
-                    assertContractAbsent(lockedRead, selectedId);
-                    selectedPlace = workspace === "worktree"
-                        ? allocateWorktreePlaceFromRead(lockedRead, input.randomBytes?.(attempt) ?? randomBytesDefault())
-                        : undefined;
-                    entry = makeBindEntry({
-                        id: selectedId, at, actor: input.actor, draft: selectedDraft, base: prepared.entryBase,
-                        target, after: canonicalAfter, workspace, place: selectedPlace, bootstrap: bootstrapPlan, taskIds: prepared.taskIds,
-                    });
-                    admittedScopeOverlaps = await admitScopeRegistration(stableRoot, {
-                        contractId: entry.contract,
-                        scope: bindEffectiveScope(entry),
-                        tree: entry.data.base,
-                        ...(input.exclusive === undefined ? {} : { exclusive: input.exclusive }),
-                    }, lockedRead);
-                    const written = await publishBind({
-                        cwd: stableRoot,
-                        entry,
-                        expectedLedgerHead: lockedRead.observedLedgerHead,
-                        delivery: { ref: repositoryDeliveryRef(entry.contract), head: prepared.entryBase },
-                        taskBoard: prepared.taskBoard,
-                    });
-                    if (written.family === "committed") {
-                        try {
-                            await taskTransaction.replace(prepared.taskIds.map((taskId) => {
-                                const source = prepared.replay.linkedSources.find((candidate) => candidate.path.endsWith(`/${taskId}.md`) || candidate.path.endsWith(`\\${taskId}.md`));
-                                if (!source)
-                                    throw new FlowError("INTERNAL_STATE", `prepared task bind has no source for ${taskId}`);
-                                return { id: taskId, text: source.text };
-                            }));
-                            const staged = await runGitProcess(stableRoot, ["add", "--", ...prepared.replay.paths]);
-                            if (staged.status !== 0 || staged.error)
-                                throw staged.error ?? new Error(staged.stderr);
-                            preparedTaskProjectionSucceeded = true;
-                        }
-                        catch {
-                            // Authority is already committed. The ordinary derived replay
-                            // below owns truthful retry/contained classification.
-                        }
-                    }
-                    if (written.family === "indeterminate")
-                        committedOrThrow(written, "BIND_TRANSACTION");
-                    return written;
-                },
-            });
-            if (attempted.result.family === "committed") {
-                settled = attempted;
-                break;
-            }
-        }
-        if (!settled)
-            throw new FlowError("CONCURRENT_MODIFICATION", "BIND_TRANSACTION_REFUSED: repository authority changed during four bind attempts");
-        preparedTask = settled.preparation;
-        const committed = committedOrThrow(settled.result, "BIND_TRANSACTION");
-        committedHead = committed.ledgerHead;
-        committedEntryObjectId = committed.entryObjectId;
-    }
-    else {
-        let committed;
-        for (let attempt = 0; attempt < 4; attempt += 1) {
-            const observed = await observeEntry();
-            const branch = observed.branch;
-            const target = normalizeTargetRef(branch.branch);
-            const read = observed.read;
-            admittedRead = read;
-            validateBindAfter(read, after);
-            await selectCandidate(ordinaryDraft, read);
-            entry = makeBindEntry({
-                id: selectedId, at, actor: input.actor, draft: selectedDraft, base: branch.head,
-                target, after, workspace, place: selectedPlace, bootstrap: bootstrapPlan,
-            });
-            admittedScopeOverlaps = await admitScopeRegistration(stableRoot, {
-                contractId: entry.contract,
-                scope: bindEffectiveScope(entry),
-                tree: entry.data.base,
-                ...(input.exclusive === undefined ? {} : { exclusive: input.exclusive }),
-            }, read);
-            const bindWrite = await publishBind({
-                cwd: stableRoot,
-                entry,
-                expectedLedgerHead: read.observedLedgerHead,
-                delivery: { ref: repositoryDeliveryRef(entry.contract), head: entry.data.base },
-            });
-            if (bindWrite.family === "committed") {
-                committed = bindWrite;
-                committedHead = bindWrite.ledgerHead;
-                committedEntryObjectId = bindWrite.entryObjectId;
-                break;
-            }
-            if (bindWrite.family === "indeterminate")
-                committedOrThrow(bindWrite, "BIND_TRANSACTION");
-        }
-        if (!committed) {
-            throw new FlowError("CONCURRENT_MODIFICATION", "BIND_TRANSACTION_REFUSED: repository authority changed during four bind attempts");
-        }
-    }
-    const repository = advanceRepositorySnapshotWithBind({
-        repository: admittedRead,
-        ledgerHead: repositoryLedgerHead(committedHead),
-        entryObjectId: committedEntryObjectId,
-        entry: entry,
-    });
-    const committedContract = lookupCurrentContract(repository, entry.contract);
-    if (committedContract.status !== "healthy") {
-        throw new FlowError("INTERNAL_STATE", `committed bind ${entry.contract} is unavailable (${committedContract.status})`);
-    }
-    const carrierTarget = entry.data.workspace === "here"
-        ? { status: "available", root: stableRoot, path: `${stableRoot}/.keiyaku/KEIYAKU.md`, workspace: "here" }
-        : { status: "unavailable", workspace: "worktree", reason: `contract ${entry.contract} has no verified registered engine worktree` };
-    const snapshot = {
-        stableRoot,
-        observation: {
-            repository,
-            lifecycle: committedContract.model,
-            target: carrierTarget,
-            pins: {
-                repositoryLedgerHead: repositoryLedgerHead(committedHead),
-                target: { ref: entry.data.target, head: entry.data.base },
-                delivery: { ref: repositoryDeliveryRef(entry.contract), head: entry.data.base },
-            },
-        },
-    };
-    return await reconcileCommittedBindFromSnapshot({
-        cwd: stableRoot,
-        contractId: entry.contract,
-        actor: input.actor,
-        nowMs: input.nowMs,
-        ...(input.signal ? { signal: input.signal } : {}),
-        ...(input.createWorktree ? { createWorktree: input.createWorktree } : {}),
-        ...(input.onProgress ? { onProgress: input.onProgress } : {}),
-        ...(input.bootstrapRunner ? { bootstrapRunner: input.bootstrapRunner } : {}),
-        ...(input.bootstrapDependencies ? { bootstrapDependencies: input.bootstrapDependencies } : {}),
-        ...(preparedTask ? { preparedTask } : {}),
-        ...(preparedTaskProjectionSucceeded ? { preparedTaskProjectionSucceeded } : {}),
-        dependencies: input.dependencies,
-    }, admittedScopeOverlaps, snapshot);
-}