ws-spec-kit 0.1.0-beta.0

package/dist/storage/control-plane.js

@@ -0,0 +1,688 @@
+import { mkdir, open, readFile, realpath, rmdir } from "node:fs/promises";
+import path from "node:path";
+import * as canonicalizeModule from "canonicalize";
+import { parse } from "yaml";
+import { parseApplicationSnapshot } from "../application/snapshot.js";
+import { deriveInitialStages } from "../application/initial-stages.js";
+import { sha256 } from "../domain/digests.js";
+import { verifySourceArtifact } from "../registry/connectors/requirement-source.js";
+import { assertExternalReceipts } from "../domain/external-receipt.js";
+import { parseTddCycleEvidence, parseTrustedEvidence, testAssetScopeManifest, testFileManifest, trustedTestAssetFiles } from "../engine/tdd/red-gate.js";
+import { transitionStage, transitionWorkItem } from "../domain/states.js";
+import { interruptedRetry } from "../engine/control/retry.js";
+import { emptyRuntimeRiskSignals } from "../application/profile.js";
+import { loadRepository } from "./repository.js";
+import { appendEventUnlocked, EventStoreError, readEvents, recoverStaleControlPlaneLock, repairIncompleteEventTail, withControlPlaneLock } from "./events.js";
+import { writeFileAtomic } from "./files.js";
+import { assertExternalActionProjection } from "../engine/external-effects/authorization.js";
+import { workPackageIdentityDigest } from "../domain/work-package-identity.js";
+export const applicationCloseEvidenceKey = "application.close";
+function assertExternalProjectionContract(stored) {
+    const actions = stored.externalActions;
+    const idempotency = stored.externalActionIdempotency;
+    if (!Object.hasOwn(stored, "externalActions") || actions === null || typeof actions !== "object" || Array.isArray(actions)
+        || !Object.hasOwn(stored, "externalActionIdempotency") || idempotency === null
+        || typeof idempotency !== "object" || Array.isArray(idempotency)) {
+        throw new ControlPlaneStorageError("WSSPEC_RUNTIME_PROJECTION_INCOMPATIBLE", "运行投影缺少 externalActions/externalActionIdempotency；当前版本不提供隐式迁移。");
+    }
+}
+export class ControlPlaneStorageError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ControlPlaneStorageError";
+    }
+}
+const canonicalize = canonicalizeModule.default;
+function sameCanonicalValue(left, right) {
+    const encoded = canonicalize(left);
+    return encoded !== undefined && encoded === canonicalize(right);
+}
+function sourceReferenceFromEvents(events, workItemId) {
+    const captured = events.filter((event) => event.eventType === "source.captured");
+    if (captured.length !== 1) {
+        throw new ControlPlaneStorageError("WSSPEC_SOURCE_SNAPSHOT_CHANGED", "Work Item 缺少唯一可信 Source 捕获事件。");
+    }
+    const result = captured[0].result;
+    const value = result !== null && typeof result === "object" && !Array.isArray(result)
+        ? result.value
+        : undefined;
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new ControlPlaneStorageError("WSSPEC_SOURCE_SNAPSHOT_CHANGED", "Source 捕获事件引用不完整。");
+    }
+    const reference = value;
+    if (Object.keys(reference).sort().join("\0") !== ["artifactId", "digest", "path"].join("\0")
+        || typeof reference.artifactId !== "string" || typeof reference.path !== "string" || typeof reference.digest !== "string"
+        || !reference.path.startsWith(`.wsspec/work-items/${workItemId}/source/`)) {
+        throw new ControlPlaneStorageError("WSSPEC_SOURCE_SNAPSHOT_CHANGED", "Source 捕获事件引用不完整。");
+    }
+    return {
+        artifactType: "requirement-source",
+        schemaVersion: 1,
+        artifactId: reference.artifactId,
+        path: reference.path,
+        revision: 1,
+        contentHash: reference.digest,
+        mediaType: "application/json",
+    };
+}
+function assertedTddEvidence(projection) {
+    const prefix = `tdd:${projection.workItemId}:`;
+    const entries = Object.entries(projection.evidence).filter(([key]) => key.startsWith("tdd:"));
+    if (entries.length === 0)
+        return {};
+    const red = parseTrustedEvidence(projection.evidence[`${prefix}red`]);
+    if (red === undefined || red.phase !== "red" || red.taskId !== projection.workItemId) {
+        throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", "事件重放包含无效或不兼容的 Red Evidence。");
+    }
+    let cycle;
+    const greens = new Map();
+    for (const [key, value] of entries) {
+        if (key === `${prefix}red`)
+            continue;
+        if (key === `${prefix}cycle`) {
+            cycle = parseTddCycleEvidence(value);
+            if (cycle === undefined || cycle.taskId !== projection.workItemId || cycle.redEvidenceId !== red.evidenceId
+                || cycle.commandId !== red.commandId || cycle.testAssetsDigest !== red.testAssetsDigest
+                || !sameCanonicalValue(cycle.testPaths, red.testPaths)
+                || !sameCanonicalValue(cycle.testPathRules, red.testPathRules)
+                || !sameCanonicalValue(cycle.testAssets, red.testAssets)
+                || !sameCanonicalValue(cycle.testAssetPaths, red.testAssetPaths)
+                || !sameCanonicalValue(cycle.testAssetRoots, red.testAssetRoots)
+                || !sameCanonicalValue(cycle.productPaths, red.productPaths)) {
+                throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", "事件重放包含无效或不兼容的 TDD Cycle Evidence。");
+            }
+            continue;
+        }
+        if (!key.startsWith(`${prefix}green:`))
+            throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", `事件重放包含未知 TDD Evidence key：${key}`);
+        const green = parseTrustedEvidence(value);
+        if (green === undefined || green.phase !== "green" || green.taskId !== projection.workItemId
+            || key !== `${prefix}green:${green.evidenceId}`
+            || green.commandId !== red.commandId || green.commandDigest !== red.commandDigest
+            || green.testPathsDigest !== red.testPathsDigest || green.testAssetsDigest !== red.testAssetsDigest
+            || !sameCanonicalValue(green.testPaths, red.testPaths)
+            || !sameCanonicalValue(green.testFiles, red.testFiles)
+            || !sameCanonicalValue(green.testPathRules, red.testPathRules)
+            || !sameCanonicalValue(trustedTestAssetFiles(green.testAssets, green), trustedTestAssetFiles(red.testAssets, red))
+            || !sameCanonicalValue(green.testAssetPaths, red.testAssetPaths)
+            || !sameCanonicalValue(green.testAssetRoots, red.testAssetRoots)
+            || !sameCanonicalValue(green.productPaths, red.productPaths)) {
+            throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", "事件重放包含未绑定当前 Red 的 Green Evidence。");
+        }
+        greens.set(green.evidenceId, green);
+    }
+    if (cycle !== undefined && (!greens.has(cycle.greenEvidenceId)
+        || (cycle.refactorEvidenceId !== undefined && !greens.has(cycle.refactorEvidenceId)))) {
+        throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", "事件重放的 TDD Cycle 引用了不存在或不兼容的 Green Evidence。");
+    }
+    return { red, ...(cycle === undefined ? {} : { cycle }) };
+}
+async function assertRecoveredTddScope(worktree, projection) {
+    const { red } = assertedTddEvidence(projection);
+    if (red === undefined)
+        return;
+    let tests;
+    let assets;
+    try {
+        [tests, assets] = await Promise.all([
+            testFileManifest(worktree, red.testPaths, red.testPathRules),
+            testAssetScopeManifest(worktree, { testAssetPaths: red.testAssetPaths, testAssetRoots: red.testAssetRoots, productPaths: red.productPaths }),
+        ]);
+    }
+    catch {
+        throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", "事件恢复时测试资产作用域已新增、删除或修改，旧 Red Evidence 失效。");
+    }
+    if (tests.digest !== red.testPathsDigest || assets.digest !== red.testAssetsDigest) {
+        throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", `事件恢复时测试资产作用域摘要失配（tests ${red.testPathsDigest} -> ${tests.digest}; assets ${red.testAssetsDigest} -> ${assets.digest}）。`);
+    }
+}
+async function readApplicationAnchorFile(controlPlane) {
+    try {
+        const anchor = JSON.parse(await readFile(path.join(controlPlane, "application-anchor.json"), "utf8"));
+        if (anchor.version !== 1 || typeof anchor.workItemId !== "string" || typeof anchor.manifestDigest !== "string" || typeof anchor.ownerToken !== "string") {
+            throw new ControlPlaneStorageError("WSSPEC_APPLICATION_ANCHOR_INVALID", "Application 锚点不完整。");
+        }
+        return anchor;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+async function resolveControlPlane(cwd, workItemId) {
+    const repository = await loadRepository(cwd);
+    const locatorPath = path.join(repository.commonDir, "wsspec", "work-items", workItemId, "locator.json");
+    let locator;
+    try {
+        locator = JSON.parse(await readFile(locatorPath, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new ControlPlaneStorageError("WSSPEC_WORK_ITEM_NOT_FOUND", `找不到 Work Item：${workItemId}`);
+        }
+        throw error;
+    }
+    if (locator.repositoryId !== repository.repositoryId || locator.workItemId !== workItemId || typeof locator.worktree !== "string") {
+        throw new ControlPlaneStorageError("WSSPEC_REPOSITORY_ID_MISMATCH", "Work Item locator 与当前仓库身份不一致。");
+    }
+    const repositoryCache = JSON.parse(await readFile(path.join(repository.commonDir, "wsspec", "repository.json"), "utf8"));
+    if (repositoryCache.repositoryId !== repository.repositoryId || typeof repositoryCache.repositoryRoot !== "string") {
+        throw new ControlPlaneStorageError("WSSPEC_REPOSITORY_ID_MISMATCH", "Git common-dir 仓库缓存身份不一致。");
+    }
+    if (path.isAbsolute(locator.worktree) || locator.worktree.split(/[\\/]/u).includes("..")) {
+        throw new ControlPlaneStorageError("WSSPEC_WORK_ITEM_LOCATION_INVALID", "Work Item locator 必须指向仓库内相对 worktree。");
+    }
+    let cachedRoot;
+    let worktree;
+    try {
+        cachedRoot = await realpath(repositoryCache.repositoryRoot);
+        worktree = await realpath(path.resolve(cachedRoot, locator.worktree));
+    }
+    catch {
+        throw new ControlPlaneStorageError("WSSPEC_WORK_ITEM_LOCATION_INVALID", "Work Item locator 指向的 worktree 不存在。");
+    }
+    const worktreeRelative = path.relative(cachedRoot, worktree);
+    if (worktreeRelative === "" || worktreeRelative.startsWith("..") || path.isAbsolute(worktreeRelative)) {
+        throw new ControlPlaneStorageError("WSSPEC_WORK_ITEM_LOCATION_INVALID", "Work Item locator 的真实路径越出仓库边界。");
+    }
+    return {
+        directory: path.join(repository.commonDir, "wsspec", "work-items", workItemId, "control-plane"),
+        repositoryId: repository.repositoryId,
+        repositoryRoot: cachedRoot,
+        worktree: worktreeRelative,
+    };
+}
+function withoutLocation(projection) {
+    const { controlPlane: _controlPlane, ...stored } = projection;
+    return stored;
+}
+export async function writeProjection(projection) {
+    await writeFileAtomic(path.join(projection.controlPlane, "runtime.json"), `${JSON.stringify(withoutLocation(projection), null, 2)}\n`);
+}
+async function writeFileExclusive(target, content) {
+    const handle = await open(target, "wx", 0o600);
+    try {
+        await handle.writeFile(content, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function writeApplicationAnchor(input) {
+    const resolved = await resolveControlPlane(input.cwd, input.workItemId);
+    await mkdir(resolved.directory);
+    const anchor = { version: 1, workItemId: input.workItemId, manifestDigest: input.manifestDigest, ownerToken: input.ownerToken };
+    try {
+        await writeFileExclusive(path.join(resolved.directory, "application-anchor.json"), `${JSON.stringify(anchor, null, 2)}\n`);
+    }
+    catch (error) {
+        await rmdir(resolved.directory).catch((cleanupError) => {
+            if (!["ENOTEMPTY", "EEXIST"].includes(cleanupError.code ?? ""))
+                throw cleanupError;
+        });
+        throw error;
+    }
+}
+export async function readApplicationAnchor(cwd, workItemId) {
+    const resolved = await resolveControlPlane(cwd, workItemId);
+    const anchor = await readApplicationAnchorFile(resolved.directory);
+    if (anchor !== undefined && anchor.workItemId !== workItemId) {
+        throw new ControlPlaneStorageError("WSSPEC_REPOSITORY_ID_MISMATCH", "Application 锚点与 Work Item 身份不一致。");
+    }
+    return anchor;
+}
+export async function readCapturedSourceReference(cwd, workItemId) {
+    const resolved = await resolveControlPlane(cwd, workItemId);
+    return readCapturedSourceReferenceFromControlPlane(resolved.directory, workItemId);
+}
+export async function readCapturedSourceReferenceFromControlPlane(controlPlane, workItemId) {
+    const events = await readEvents(controlPlane).catch((error) => {
+        if (error instanceof EventStoreError)
+            throw new ControlPlaneStorageError(error.code, error.message);
+        throw error;
+    });
+    return sourceReferenceFromEvents(events, workItemId);
+}
+export async function authenticateApplicationSourceAuthority(input) {
+    const itemRoot = path.join(input.worktree, ".wsspec", "work-items", input.workItemId);
+    let applicationText;
+    try {
+        applicationText = await readFile(path.join(itemRoot, "snapshot", "application.json"), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new ControlPlaneStorageError("WSSPEC_SOURCE_SNAPSHOT_CHANGED", "Work Item 缺少可信 Application 快照。");
+        }
+        throw error;
+    }
+    const manifestText = await readFile(path.join(itemRoot, "work-item.yaml"), "utf8");
+    const anchor = await readApplicationAnchorFile(input.controlPlane);
+    if (anchor === undefined) {
+        throw new ControlPlaneStorageError("WSSPEC_SOURCE_SNAPSHOT_CHANGED", "Work Item 缺少可信 Application 锚点。");
+    }
+    if (anchor.workItemId !== input.workItemId || sha256(manifestText) !== anchor.manifestDigest) {
+        throw new ControlPlaneStorageError("WSSPEC_WORK_ITEM_MANIFEST_CHANGED", "Work Item manifest 与可信 Application 锚点不一致。");
+    }
+    const manifest = parse(manifestText);
+    if (typeof manifest.execution?.workflowDigest !== "string" || sha256(applicationText) !== manifest.execution.workflowDigest) {
+        throw new ControlPlaneStorageError("WSSPEC_APPLICATION_SNAPSHOT_CHANGED", "Application 快照摘要与 Work Item manifest 不一致。");
+    }
+    let application;
+    try {
+        application = parseApplicationSnapshot(JSON.parse(applicationText));
+    }
+    catch {
+        throw new ControlPlaneStorageError("WSSPEC_APPLICATION_SNAPSHOT_INVALID", "Application 快照不是合法的严格快照。");
+    }
+    if (manifest.workItemId !== input.workItemId
+        || (input.repositoryId !== undefined && manifest.repositoryId !== input.repositoryId)) {
+        throw new ControlPlaneStorageError("WSSPEC_REPOSITORY_ID_MISMATCH", "Work Item manifest 与控制面身份不一致。");
+    }
+    const events = await readEvents(input.controlPlane).catch((error) => {
+        if (error instanceof EventStoreError)
+            throw new ControlPlaneStorageError(error.code, error.message);
+        throw error;
+    });
+    const eventSourceReference = sourceReferenceFromEvents(events, input.workItemId);
+    if (typeof manifest.source?.artifactId !== "string" || typeof manifest.source.snapshot !== "string"
+        || typeof manifest.source.artifactDigest !== "string" || typeof manifest.source.contentDigest !== "string"
+        || typeof manifest.source.type !== "string") {
+        throw new ControlPlaneStorageError("WSSPEC_SOURCE_SNAPSHOT_CHANGED", "Work Item 缺少严格 Source Artifact 引用。");
+    }
+    const manifestSourceReference = {
+        artifactType: "requirement-source",
+        schemaVersion: 1,
+        artifactId: manifest.source.artifactId,
+        path: `.wsspec/work-items/${input.workItemId}/${manifest.source.snapshot}`,
+        revision: 1,
+        contentHash: manifest.source.artifactDigest,
+        mediaType: "application/json",
+    };
+    if (!sameCanonicalValue(eventSourceReference, manifestSourceReference)
+        || !sameCanonicalValue(eventSourceReference, application.source)) {
+        throw new ControlPlaneStorageError("WSSPEC_SOURCE_SNAPSHOT_CHANGED", "Application、Work Item manifest 与可信 Source 捕获事件不一致。");
+    }
+    const source = await verifySourceArtifact(input.worktree, input.workItemId, eventSourceReference);
+    if (source.contentDigest !== manifest.source.contentDigest || source.type !== manifest.source.type) {
+        throw new ControlPlaneStorageError("WSSPEC_SOURCE_SNAPSHOT_CHANGED", "Source Artifact 与 Work Item manifest 不一致。");
+    }
+    return {
+        application,
+        applicationText,
+        events,
+        itemRoot,
+        manifest,
+        source,
+        sourceReference: eventSourceReference,
+    };
+}
+export async function writeArchiveSnapshot(input) {
+    assertExternalReceipts(input.projection.evidence, "WSSPEC_EVENT_CHAIN_INVALID");
+    const { controlPlane: _controlPlane, ...publicProjection } = input.projection;
+    const audit = {
+        version: 1,
+        repositoryId: input.projection.repositoryId,
+        workItemId: input.projection.workItemId,
+        closedAt: input.closedAt,
+        workspaceTreeDigest: input.workspaceTreeDigest,
+        artifactTreeDigest: input.artifactTreeDigest,
+        terminalEventHash: input.projection.lastEventHash,
+        projection: publicProjection,
+    };
+    await writeFileAtomic(path.join(input.worktree, ".wsspec", "archive", input.projection.workItemId, "audit.json"), `${JSON.stringify(audit, null, 2)}\n`);
+}
+export async function initializeControlPlane(input) {
+    const resolved = await resolveControlPlane(input.cwd, input.workItemId);
+    await mkdir(resolved.directory, { recursive: true });
+    const projection = {
+        version: 1,
+        repositoryId: resolved.repositoryId,
+        workItemId: input.workItemId,
+        workItem: input.initialWorkItem ?? { status: "draft" },
+        stages: input.initialStages ?? Object.fromEntries(input.stages.map((stage) => [stage, { status: "pending" }])),
+        lastSequence: 0,
+        lastEventHash: null,
+        idempotency: {},
+        profile: input.initialProfile ?? { mode: "quick", selected: "quick", provisional: false, reasonRuleIds: [], riskSignals: emptyRuntimeRiskSignals() },
+        claims: {},
+        contexts: {},
+        approvals: {},
+        externalActions: {},
+        externalActionIdempotency: {},
+        evidence: {},
+        loops: {},
+        retries: {},
+        readOnly: false,
+        controlPlane: resolved.directory,
+    };
+    await writeFileExclusive(path.join(projection.controlPlane, "runtime.json"), `${JSON.stringify(withoutLocation(projection), null, 2)}\n`);
+    return projection;
+}
+export async function readControlPlane(cwd, workItemId) {
+    const resolved = await resolveControlPlane(cwd, workItemId);
+    const stored = JSON.parse(await readFile(path.join(resolved.directory, "runtime.json"), "utf8"));
+    if (stored.repositoryId !== resolved.repositoryId || stored.workItemId !== workItemId) {
+        throw new ControlPlaneStorageError("WSSPEC_REPOSITORY_ID_MISMATCH", "运行投影与当前仓库身份不一致。");
+    }
+    assertExternalProjectionContract(stored);
+    const projection = {
+        ...stored,
+        profile: stored.profile === undefined
+            ? { mode: "quick", selected: "quick", provisional: false, reasonRuleIds: [], riskSignals: emptyRuntimeRiskSignals() }
+            : { ...stored.profile, riskSignals: stored.profile.riskSignals ?? emptyRuntimeRiskSignals() },
+        claims: stored.claims ?? {},
+        contexts: stored.contexts ?? {},
+        approvals: stored.approvals ?? {},
+        externalActions: stored.externalActions ?? {},
+        externalActionIdempotency: stored.externalActionIdempotency ?? {},
+        evidence: stored.evidence ?? {},
+        loops: stored.loops ?? {},
+        retries: stored.retries ?? {},
+        readOnly: stored.readOnly ?? false,
+        controlPlane: resolved.directory,
+    };
+    assertExternalActionProjection(projection.externalActions, projection.externalActionIdempotency);
+    return projection;
+}
+export function replayEvents(input) {
+    let recovered = {
+        version: 1,
+        repositoryId: input.repositoryId,
+        workItemId: input.workItemId,
+        workItem: input.initialWorkItem ?? { status: "draft" },
+        stages: input.initialStages ?? Object.fromEntries(input.stageIds.map((stage) => [stage, { status: "pending" }])),
+        lastSequence: 0,
+        lastEventHash: null,
+        idempotency: {},
+        profile: input.initialProfile ?? { mode: "quick", selected: "quick", provisional: false, reasonRuleIds: [], riskSignals: emptyRuntimeRiskSignals() },
+        claims: {},
+        contexts: {},
+        approvals: {},
+        externalActions: {},
+        externalActionIdempotency: {},
+        evidence: {},
+        loops: {},
+        retries: {},
+        readOnly: false,
+        controlPlane: input.controlPlane,
+    };
+    for (const event of input.events) {
+        if (event.repositoryId !== recovered.repositoryId || event.workItemId !== recovered.workItemId) {
+            throw new ControlPlaneStorageError("WSSPEC_REPOSITORY_ID_MISMATCH", "事件与当前仓库或 Work Item 身份不一致。");
+        }
+        if (event.eventType === "work-item.transitioned") {
+            recovered = { ...recovered, workItem: transitionWorkItem(recovered.workItem, { type: "transition", to: event.to }) };
+        }
+        else if (event.eventType === "stage.transitioned") {
+            const stageId = event.stageId;
+            if (stageId === null || recovered.stages[stageId] === undefined) {
+                throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", "Stage 事件引用了未知 Stage。");
+            }
+            recovered = { ...recovered, stages: { ...recovered.stages, [stageId]: transitionStage(recovered.stages[stageId], { type: "transition", to: event.to }) } };
+        }
+        else if (event.eventType === "artifact.authored") {
+            const value = event.result.value;
+            if (value === null || typeof value !== "object" || Array.isArray(value)) {
+                throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", "Artifact authoring 事件缺少安全摘要引用。");
+            }
+        }
+        else {
+            const result = event.result;
+            if (result.projection === undefined)
+                throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", `事件 ${event.eventType} 缺少可重放投影。`);
+            recovered = { ...recovered, ...result.projection };
+            assertExternalActionProjection(recovered.externalActions, recovered.externalActionIdempotency);
+            assertExternalReceipts(recovered.evidence, "WSSPEC_EVENT_CHAIN_INVALID");
+            assertedTddEvidence(recovered);
+        }
+        recovered.lastSequence = event.sequence;
+        recovered.lastEventHash = event.eventHash;
+        recovered.idempotency[event.idempotencyKey] = event.sequence;
+    }
+    recovered.profile = {
+        ...recovered.profile,
+        riskSignals: recovered.profile.riskSignals ?? emptyRuntimeRiskSignals(),
+    };
+    recovered.readOnly = recovered.workItem.status === "closed";
+    return recovered;
+}
+export async function recoverControlPlane(input) {
+    const resolved = await resolveControlPlane(input.cwd, input.workItemId);
+    await recoverStaleControlPlaneLock(resolved.directory);
+    return withControlPlaneLock(resolved.directory, async () => {
+        await repairIncompleteEventTail(resolved.directory);
+        let durableProjection;
+        try {
+            const stored = JSON.parse(await readFile(path.join(resolved.directory, "runtime.json"), "utf8"));
+            if (stored.repositoryId !== resolved.repositoryId || stored.workItemId !== input.workItemId) {
+                throw new ControlPlaneStorageError("WSSPEC_REPOSITORY_ID_MISMATCH", "运行投影与当前仓库身份不一致。");
+            }
+            assertExternalProjectionContract(stored);
+            durableProjection = stored;
+        }
+        catch (error) {
+            if (error instanceof ControlPlaneStorageError)
+                throw error;
+            if (!(error instanceof SyntaxError) && error.code !== "ENOENT")
+                throw error;
+        }
+        const worktree = path.join(resolved.repositoryRoot, resolved.worktree);
+        const authority = await authenticateApplicationSourceAuthority({
+            controlPlane: resolved.directory,
+            worktree,
+            workItemId: input.workItemId,
+            repositoryId: resolved.repositoryId,
+        });
+        const events = authority.events;
+        let stageIds;
+        let initialWorkItem;
+        let initialStages;
+        let initialProfile;
+        const application = authority.application;
+        const profile = application.profiles[application.selectedProfile];
+        stageIds = profile.order;
+        initialWorkItem = { status: "active" };
+        initialStages = deriveInitialStages(profile);
+        initialProfile = { mode: application.selectedProfile, selected: application.selectedProfile, provisional: false, reasonRuleIds: [], riskSignals: emptyRuntimeRiskSignals() };
+        if (durableProjection !== undefined) {
+            const anchoredEvent = durableProjection.lastSequence === 0 ? undefined : events[durableProjection.lastSequence - 1];
+            if (durableProjection.lastSequence > events.length ||
+                (durableProjection.lastSequence > 0 && anchoredEvent?.eventHash !== durableProjection.lastEventHash)) {
+                throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", "事件日志短于或偏离持久化投影锚点。");
+            }
+        }
+        let recovered = replayEvents({
+            repositoryId: resolved.repositoryId,
+            workItemId: input.workItemId,
+            stageIds,
+            controlPlane: resolved.directory,
+            events,
+            ...(initialWorkItem === undefined ? {} : { initialWorkItem }),
+            ...(initialStages === undefined ? {} : { initialStages }),
+            ...(initialProfile === undefined ? {} : { initialProfile }),
+        });
+        await assertRecoveredTddScope(path.join(resolved.repositoryRoot, resolved.worktree), recovered);
+        const recoveryTime = new Date();
+        const abandonedStages = Object.entries(recovered.stages).filter(([stageId, stage]) => {
+            if (stage.status === "running")
+                return true;
+            if (stage.status !== "claimed")
+                return false;
+            const expiresAt = Date.parse(recovered.claims[stageId]?.expiresAt ?? "");
+            return !Number.isFinite(expiresAt) || expiresAt <= recoveryTime.getTime();
+        }).map(([stageId]) => stageId);
+        const durableApprovalIds = new Set(Object.entries(recovered.approvals)
+            .filter(([, approval]) => approval.status === "pending"
+            && recovered.workItem.status === "awaiting_approval"
+            && recovered.stages[approval.stageId]?.status === "awaiting_approval")
+            .map(([requestId]) => requestId));
+        const durableApprovalStages = new Set([...durableApprovalIds].map((requestId) => recovered.approvals[requestId].stageId));
+        const invalidPendingApprovalIds = new Set(Object.entries(recovered.approvals)
+            .filter(([requestId, approval]) => approval.status === "pending" && !durableApprovalIds.has(requestId))
+            .map(([requestId]) => requestId));
+        const approvalStages = Object.entries(recovered.stages)
+            .filter(([stageId, stage]) => stage.status === "awaiting_approval" && !durableApprovalStages.has(stageId))
+            .map(([stageId]) => stageId);
+        const abandonedStageSet = new Set(abandonedStages);
+        const preDispatchExternalActionIds = Object.entries(recovered.externalActions)
+            .filter(([, action]) => abandonedStageSet.has(action.request.stepId)
+            && (action.status === "prepared" || action.status === "approved"
+                || (action.status === "executing" && action.dispatch === "not_sent")))
+            .map(([requestId]) => requestId);
+        const preservedExternalStageIds = [...new Set(Object.values(recovered.externalActions)
+                .filter((action) => abandonedStageSet.has(action.request.stepId)
+                && (action.status === "reconciliation_required" || action.status === "verified" || action.status === "failed"
+                    || (action.status === "executing" && action.dispatch === "sent_or_unknown")))
+                .map((action) => action.request.stepId))];
+        const preservedExternalStageSet = new Set(preservedExternalStageIds);
+        const uncertainExternalActionIds = Object.entries(recovered.externalActions)
+            .filter(([, action]) => action.status === "executing" && action.dispatch === "sent_or_unknown")
+            .map(([requestId]) => requestId);
+        const recoveryStages = [...new Set([
+                ...abandonedStages.filter((stageId) => !preservedExternalStageSet.has(stageId)),
+                ...approvalStages,
+            ])];
+        const recoverWorkItem = recovered.workItem.status === "awaiting_approval" && durableApprovalIds.size === 0;
+        if (recoveryStages.length > 0 || recoverWorkItem || invalidPendingApprovalIds.size > 0
+            || uncertainExternalActionIds.length > 0 || preDispatchExternalActionIds.length > 0 || preservedExternalStageIds.length > 0) {
+            const recoveredAt = recoveryTime.toISOString();
+            const next = {
+                ...recovered,
+                workItem: recoverWorkItem ? { status: "active" } : recovered.workItem,
+                stages: { ...recovered.stages },
+                claims: { ...recovered.claims },
+                contexts: { ...recovered.contexts },
+                approvals: { ...recovered.approvals },
+                externalActions: { ...recovered.externalActions },
+                externalActionIdempotency: { ...recovered.externalActionIdempotency },
+                evidence: { ...recovered.evidence },
+                retries: { ...recovered.retries },
+            };
+            for (const requestId of preDispatchExternalActionIds) {
+                const action = next.externalActions[requestId];
+                if (action === undefined)
+                    throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", "待失效外部动作不存在。");
+                delete next.externalActions[requestId];
+                delete next.externalActionIdempotency[action.request.idempotencyKey];
+                delete next.evidence[`external-rejection:${requestId}`];
+            }
+            for (const stageId of recoveryStages) {
+                const stepInstanceId = recovered.claims[stageId]?.stageId ?? stageId;
+                const retry = Object.hasOwn(next.retries, stepInstanceId) ? next.retries[stepInstanceId] : undefined;
+                if (retry !== undefined)
+                    next.retries[stepInstanceId] = interruptedRetry(retry);
+                next.stages[stageId] = (Object.hasOwn(next.retries, stepInstanceId) ? next.retries[stepInstanceId] : undefined)?.status === "exhausted"
+                    ? { status: "failed" }
+                    : { status: "ready" };
+                delete next.claims[stageId];
+                delete next.contexts[stageId];
+            }
+            for (const stageId of preservedExternalStageIds) {
+                const claim = next.claims[stageId];
+                const context = next.contexts[stageId];
+                if (claim === undefined || context?.workPackage?.attemptId !== claim.attemptId
+                    || context.workPackage.lease?.token !== claim.claimToken) {
+                    throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", "外部动作恢复缺少原 Attempt/Lease 上下文。");
+                }
+                const claimedAt = Date.parse(claim.claimedAt);
+                const expiresAt = Date.parse(claim.expiresAt);
+                const leaseDuration = Number.isFinite(claimedAt) && Number.isFinite(expiresAt) && expiresAt > claimedAt
+                    ? expiresAt - claimedAt
+                    : 30 * 60 * 1_000;
+                const renewedExpiresAt = new Date(recoveryTime.getTime() + leaseDuration).toISOString();
+                const workPackage = {
+                    ...context.workPackage,
+                    lease: { ...context.workPackage.lease, expiresAt: renewedExpiresAt },
+                };
+                next.claims[stageId] = {
+                    ...claim,
+                    expiresAt: renewedExpiresAt,
+                    workPackageDigest: workPackageIdentityDigest(workPackage),
+                };
+                next.contexts[stageId] = {
+                    ...context,
+                    workPackage,
+                };
+            }
+            for (const requestId of invalidPendingApprovalIds) {
+                const approval = next.approvals[requestId];
+                next.approvals[requestId] = { ...approval, status: "expired", decidedAt: recoveredAt };
+            }
+            for (const requestId of uncertainExternalActionIds) {
+                const action = next.externalActions[requestId];
+                if (action.status !== "executing")
+                    throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", "外部动作恢复状态不一致。");
+                next.externalActions[requestId] = {
+                    status: "reconciliation_required",
+                    request: action.request,
+                    grant: action.grant,
+                    reason: "process recovery after dispatch",
+                    requiredAt: recoveredAt,
+                };
+            }
+            const previous = events.at(-1);
+            if (previous === undefined)
+                throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", "活动 Claim 缺少对应事件历史。");
+            const idempotencyKey = `recover-interrupted:${previous.eventHash}`;
+            const event = {
+                eventId: `event-${crypto.randomUUID()}`, eventType: "projection.invalidated", occurredAt: new Date().toISOString(), actor: "recovery",
+                repositoryId: recovered.repositoryId, workItemId: recovered.workItemId, stageId: null, attemptId: null,
+                from: recovered.workItem.status, to: recovered.workItem.status, idempotencyKey,
+                workflowDigest: previous.workflowDigest, configDigest: previous.configDigest, baselineTreeDigest: previous.baselineTreeDigest,
+                inputWorkspaceTreeDigest: previous.outputWorkspaceTreeDigest ?? previous.inputWorkspaceTreeDigest, outputWorkspaceTreeDigest: null,
+                inputDigest: sha256(JSON.stringify({
+                    recoveryStages: [...recoveryStages].sort(),
+                    preDispatchExternalActionIds: [...preDispatchExternalActionIds].sort(),
+                    preservedExternalStageIds: [...preservedExternalStageIds].sort(),
+                    uncertainExternalActionIds: [...uncertainExternalActionIds].sort(),
+                })),
+                result: {
+                    projection: {
+                        workItem: next.workItem,
+                        stages: next.stages,
+                        profile: next.profile,
+                        claims: next.claims,
+                        contexts: next.contexts,
+                        approvals: next.approvals,
+                        externalActions: next.externalActions,
+                        externalActionIdempotency: next.externalActionIdempotency,
+                        evidence: next.evidence,
+                        loops: next.loops,
+                        retries: next.retries,
+                        readOnly: next.readOnly,
+                    },
+                    value: {
+                        abandonedStages,
+                        approvalStages,
+                        preDispatchExternalActionIds,
+                        preservedExternalStageIds,
+                        uncertainExternalActionIds,
+                    },
+                },
+            };
+            const stored = await appendEventUnlocked(resolved.directory, event);
+            next.lastSequence = stored.sequence;
+            next.lastEventHash = stored.eventHash;
+            next.idempotency = { ...next.idempotency, [idempotencyKey]: stored.sequence };
+            recovered = next;
+        }
+        await writeProjection(recovered);
+        if (recovered.workItem.status === "closed") {
+            const closedEvent = [...events].reverse().find((event) => event.eventType === "work-item.closed");
+            const value = closedEvent?.result?.value;
+            const applicationClose = recovered.evidence[applicationCloseEvidenceKey];
+            const closedAt = value?.closedAt ?? applicationClose?.closedAt;
+            const workspaceTreeDigest = value?.workspaceTreeDigest ?? applicationClose?.workspaceTreeDigest;
+            const artifactTreeDigest = applicationClose?.artifactTreeDigest;
+            if (typeof closedAt !== "string" || typeof workspaceTreeDigest !== "string" || typeof artifactTreeDigest !== "string")
+                throw new ControlPlaneStorageError("WSSPEC_EVENT_CHAIN_INVALID", "关闭事件缺少归档重建数据。");
+            await writeArchiveSnapshot({ projection: recovered, worktree: path.join(resolved.repositoryRoot, resolved.worktree), closedAt, workspaceTreeDigest, artifactTreeDigest });
+        }
+        return recovered;
+    });
+}
+//# sourceMappingURL=control-plane.js.map