ws-spec-kit 0.1.0-beta.0

package/dist/application/external-action.js

@@ -0,0 +1,670 @@
+import { computeWorkspaceTreeDigest } from "../domain/digests.js";
+import { assertGrantAuthorizes, createExternalActionGrant, createExternalActionRequest, ExternalAuthorizationError, transitionExternalAction, } from "../engine/external-effects/authorization.js";
+import { canonicalDigest, externalIdempotencyKey, ExternalIdempotencyError } from "../engine/external-effects/idempotency.js";
+import { ControlPlaneError, mutateControlPlane } from "../engine/scheduler.js";
+import { readControlPlane } from "../storage/control-plane.js";
+import { readEvents, withControlPlaneLock } from "../storage/events.js";
+import { persistExternalActionPayload, prepareExternalActionPayload, removeExternalActionPayload, } from "../storage/external-action-payload.js";
+import { loadApplicationState, selectedProfile } from "./state.js";
+import { validate } from "../schemas/index.js";
+import { inspectDecodedCredentialSurface } from "../registry/connectors/secret-detector.js";
+export { ExternalAuthorizationError as ExternalActionError } from "../engine/external-effects/authorization.js";
+export function externalActionRejectionKey(requestId) {
+    return `external-rejection:${requestId}`;
+}
+function asExternalError(error) {
+    if (error instanceof ExternalAuthorizationError)
+        throw error;
+    if (error instanceof ExternalIdempotencyError) {
+        throw new ExternalAuthorizationError(error.code, error.message.replace(/^WSSPEC_[A-Z_]+:\s*/u, ""));
+    }
+    if (error instanceof ControlPlaneError && error.code === "WSSPEC_IDEMPOTENCY_CONFLICT") {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_IDEMPOTENCY_CONFLICT", "外部幂等键已绑定不同请求。");
+    }
+    throw error;
+}
+function currentAction(projection, requestId) {
+    const action = projection.externalActions[requestId];
+    if (action === undefined)
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_REQUEST_NOT_FOUND", "外部动作请求不存在。");
+    return action;
+}
+function assertActiveAttempt(projection, input, at) {
+    const claim = projection.claims[input.stepId];
+    const context = projection.contexts[input.stepId];
+    if (claim?.attemptId !== input.attemptId || claim.stageId !== input.stepId
+        || context?.workPackage?.stepId !== input.stepId || context.workPackage.attemptId !== input.attemptId
+        || context.workPackage.lease?.token !== claim.claimToken || new Date(claim.expiresAt) <= at) {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_ATTEMPT_MISMATCH", "外部动作未绑定当前未过期的活动 Attempt/Lease。");
+    }
+}
+export async function assertCurrentExternalActionContext(state, projection, request) {
+    const profile = state.snapshot.profiles[projection.profile.selected];
+    const workspaceDigest = await computeWorkspaceTreeDigest(state.worktree);
+    if (profile === undefined || request.profile !== profile.id
+        || request.profileDigest !== canonicalDigest(profile, "WSSPEC_EXTERNAL_GRANT_MISMATCH")
+        || request.workspaceDigest !== workspaceDigest
+        || request.configDigest !== state.item.execution.configDigest) {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_GRANT_MISMATCH", "外部动作授权上下文已变化，必须重新准备请求并审批。");
+    }
+}
+export function externalActionApprovalSummary(request) {
+    return {
+        provider: request.provider,
+        action: request.action,
+        target: { ...request.target },
+        digest: request.payloadDigest,
+        sideEffects: [...request.sideEffects],
+    };
+}
+function actionsReferencePayload(actions, digest) {
+    return actions !== undefined && Object.values(actions)
+        .some((action) => action.request.payloadArtifactDigest === digest);
+}
+async function removeCreatedPayloadIfUnreferenced(input) {
+    await withControlPlaneLock(input.controlPlane, async () => {
+        const projection = await readControlPlane(input.root, input.workItemId);
+        if (actionsReferencePayload(projection.externalActions, input.digest))
+            return;
+        const events = await readEvents(input.controlPlane);
+        const referencedByEvent = events.some((event) => {
+            const result = event.result;
+            return actionsReferencePayload(result?.projection?.externalActions, input.digest);
+        });
+        if (!referencedByEvent)
+            await removeExternalActionPayload({ controlPlane: input.controlPlane, digest: input.digest });
+    });
+}
+export async function prepareExternalAction(input) {
+    let createdPayload;
+    try {
+        const state = await loadApplicationState(input.root, input.workItemId);
+        const profile = selectedProfile(state.snapshot);
+        const payloadArtifact = prepareExternalActionPayload({
+            workItemId: input.workItemId,
+            stepId: input.stepId,
+            attemptId: input.attemptId,
+            provider: input.provider,
+            action: input.action,
+            target: input.target,
+            payload: input.payload,
+        });
+        const request = validate("builtin.external-action-request.v1", createExternalActionRequest({
+            version: 1,
+            workItemId: input.workItemId,
+            stepId: input.stepId,
+            attemptId: input.attemptId,
+            provider: input.provider,
+            action: input.action,
+            securityClass: input.securityClass,
+            target: input.target,
+            ...(input.externalEffectKind === undefined ? {} : { externalEffectKind: input.externalEffectKind }),
+            payload: input.payload,
+            expectedContentDigest: input.expectedContentDigest,
+            payloadArtifactDigest: payloadArtifact.digest,
+            bindingDigest: input.bindingDigest,
+            inputDigest: input.inputDigest,
+            artifactDigests: input.artifactDigests,
+            ...(input.idempotencyKey === undefined ? {} : { idempotencyKey: input.idempotencyKey }),
+            profile: profile.id,
+            profileDigest: canonicalDigest(profile, "WSSPEC_EXTERNAL_REQUEST_INVALID"),
+            workspaceDigest: await computeWorkspaceTreeDigest(state.worktree),
+            configDigest: state.item.execution.configDigest,
+            sideEffects: input.sideEffects,
+            createdAt: input.createdAt,
+            expiresAt: input.expiresAt,
+        }));
+        const derivedKey = externalIdempotencyKey(request);
+        return await mutateControlPlane({
+            cwd: input.root,
+            workItemId: input.workItemId,
+            eventType: "external-action.prepared",
+            idempotencyKey: `external-action:prepare:${request.idempotencyKey}:${request.requestDigest}`,
+            actor: input.actor,
+            stageId: input.stepId,
+            attemptId: input.attemptId,
+            operationInput: request,
+            mutate: async (projection) => {
+                const existingRequestId = projection.externalActionIdempotency[request.idempotencyKey];
+                if (existingRequestId !== undefined) {
+                    const existing = currentAction(projection, existingRequestId);
+                    if (existing.request.requestDigest !== request.requestDigest) {
+                        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_IDEMPOTENCY_CONFLICT", "外部幂等键已绑定不同请求。");
+                    }
+                    return { projection, value: existing };
+                }
+                const conflicting = Object.values(projection.externalActions).find((candidate) => candidate.request.workItemId === request.workItemId
+                    && candidate.request.stepId === request.stepId
+                    && candidate.request.attemptId === request.attemptId
+                    && candidate.request.provider === request.provider
+                    && candidate.request.action === request.action
+                    && candidate.request.target.kind === request.target.kind
+                    && candidate.request.target.stableId === request.target.stableId);
+                if (conflicting !== undefined) {
+                    throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_IDEMPOTENCY_CONFLICT", "同一 Attempt 的外部动作已绑定不同 payload。");
+                }
+                assertActiveAttempt(projection, request, new Date(input.createdAt));
+                await assertCurrentExternalActionContext(state, projection, request);
+                if (input.idempotencyKey !== undefined && input.idempotencyKey !== derivedKey) {
+                    throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_IDEMPOTENCY_INVALID", "外部幂等键不符合规范身份生成规则。");
+                }
+                const persisted = await persistExternalActionPayload({
+                    controlPlane: projection.controlPlane,
+                    artifact: payloadArtifact,
+                });
+                if (persisted.created)
+                    createdPayload = { controlPlane: projection.controlPlane, digest: persisted.digest };
+                const prepared = { status: "prepared", request };
+                return {
+                    projection: {
+                        ...projection,
+                        externalActions: { ...projection.externalActions, [request.requestId]: prepared },
+                        externalActionIdempotency: { ...projection.externalActionIdempotency, [request.idempotencyKey]: request.requestId },
+                    },
+                    value: prepared,
+                };
+            },
+        });
+    }
+    catch (error) {
+        if (createdPayload !== undefined) {
+            try {
+                await removeCreatedPayloadIfUnreferenced({
+                    root: input.root,
+                    workItemId: input.workItemId,
+                    ...createdPayload,
+                });
+            }
+            catch {
+                // Cleanup is conservative: retain the artifact when durable references cannot be ruled out.
+            }
+        }
+        return asExternalError(error);
+    }
+}
+export async function approveExternalAction(input) {
+    if (input.terminal.isTTY !== true)
+        throw new ExternalAuthorizationError("WSSPEC_INTERACTIVE_TTY_REQUIRED", "外部动作授权必须来自真实交互式 TTY。");
+    const applicationState = await loadApplicationState(input.root, input.workItemId);
+    const current = currentAction(applicationState.projection, input.requestId);
+    if (current.request.requestDigest !== input.expectedRequestDigest) {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_REQUEST_DIGEST_MISMATCH", "外部动作审批摘要不匹配。");
+    }
+    if (current.status !== "prepared" && current.status !== "approved") {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_STATE_TRANSITION_INVALID", "只有 prepared 外部动作可以授权。");
+    }
+    return mutateControlPlane({
+        cwd: input.root,
+        workItemId: input.workItemId,
+        eventType: "external-action.approved",
+        idempotencyKey: `external-action:approve:${input.requestId}:${current.request.requestDigest}`,
+        actor: input.actor,
+        stageId: current.request.stepId,
+        attemptId: current.request.attemptId,
+        operationInput: {
+            decision: "approved",
+            requestDigest: input.expectedRequestDigest,
+            actor: input.actor,
+            approvalDigest: input.approvalDigest,
+            profile: input.profile,
+            profileDigest: input.profileDigest,
+            workspaceDigest: input.workspaceDigest,
+            configDigest: input.configDigest,
+            expiresAt: input.expiresAt,
+        },
+        mutate: async (projection) => {
+            const action = currentAction(projection, input.requestId);
+            if (action.status !== "prepared")
+                throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_STATE_TRANSITION_INVALID", "只有 prepared 外部动作可以授权。");
+            const grant = validate("builtin.external-action-grant.v1", createExternalActionGrant({
+                request: action.request,
+                actor: input.actor,
+                approvalDigest: input.approvalDigest,
+                profile: input.profile,
+                profileDigest: input.profileDigest,
+                workspaceDigest: input.workspaceDigest,
+                configDigest: input.configDigest,
+                decidedAt: input.decidedAt,
+                expiresAt: input.expiresAt,
+            }));
+            assertActiveAttempt(projection, action.request, new Date(input.decidedAt));
+            await assertCurrentExternalActionContext(applicationState, projection, action.request);
+            const approved = transitionExternalAction(action, { status: "approved", request: action.request, grant });
+            return { projection: { ...projection, externalActions: { ...projection.externalActions, [input.requestId]: approved } }, value: approved };
+        },
+    });
+}
+export async function rejectExternalAction(input) {
+    if (input.terminal.isTTY !== true)
+        throw new ExternalAuthorizationError("WSSPEC_INTERACTIVE_TTY_REQUIRED", "外部动作拒绝决定必须来自真实交互式 TTY。");
+    const initial = currentAction(await readControlPlane(input.root, input.workItemId), input.requestId);
+    return mutateControlPlane({
+        cwd: input.root,
+        workItemId: input.workItemId,
+        eventType: "external-action.rejected",
+        idempotencyKey: `external-action:reject:${input.requestId}:${initial.request.requestDigest}`,
+        actor: input.actor,
+        stageId: initial.request.stepId,
+        attemptId: initial.request.attemptId,
+        operationInput: {
+            decision: "rejected",
+            requestId: input.requestId,
+            expectedRequestDigest: input.expectedRequestDigest,
+            actor: input.actor,
+        },
+        mutate: (projection) => {
+            const action = currentAction(projection, input.requestId);
+            if (action.request.requestDigest !== input.expectedRequestDigest) {
+                throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_REQUEST_DIGEST_MISMATCH", "外部动作拒绝摘要不匹配。");
+            }
+            if (action.status !== "prepared") {
+                throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_STATE_TRANSITION_INVALID", "只有 prepared 外部动作可以拒绝。");
+            }
+            assertActiveAttempt(projection, action.request, new Date(input.rejectedAt));
+            const rejection = {
+                requestId: action.request.requestId,
+                requestDigest: action.request.requestDigest,
+                actor: input.actor,
+                rejectedAt: input.rejectedAt,
+            };
+            return {
+                projection: {
+                    ...projection,
+                    evidence: { ...projection.evidence, [externalActionRejectionKey(input.requestId)]: rejection },
+                },
+                value: rejection,
+            };
+        },
+    });
+}
+async function persistAction(input) {
+    return mutateControlPlane({
+        cwd: input.root,
+        workItemId: input.workItemId,
+        eventType: input.eventType,
+        idempotencyKey: `external-action:${input.suffix}:${input.requestId}`,
+        actor: input.actor ?? "external-coordinator",
+        operationInput: input.operationInput,
+        mutate: async (projection) => {
+            const current = currentAction(projection, input.requestId);
+            const next = await input.update(current, projection);
+            return { projection: { ...projection, externalActions: { ...projection.externalActions, [input.requestId]: next } }, value: next };
+        },
+    });
+}
+function receipt(request, grant, input) {
+    if (input.targetStableId !== request.target.stableId
+        || (request.externalEffectKind === "issue.comment") !== (input.externalEffectId !== undefined)
+        || input.publishedContentDigest !== request.expectedContentDigest
+        || input.readBackContentDigest !== request.expectedContentDigest) {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_READBACK_MISMATCH", "外部回读的稳定目标或内容摘要不一致。");
+    }
+    return validate("builtin.external-write-receipt.v1", {
+        version: 1,
+        kind: "external-write-receipt",
+        requestId: request.requestId,
+        requestDigest: request.requestDigest,
+        grantDigest: grant.grantDigest,
+        workItemId: request.workItemId,
+        stepId: request.stepId,
+        attemptId: request.attemptId,
+        provider: request.provider,
+        action: request.action,
+        target: { ...request.target },
+        ...(request.externalEffectKind === undefined ? {} : { externalEffectKind: request.externalEffectKind }),
+        ...(input.externalEffectId === undefined ? {} : { externalEffectId: input.externalEffectId }),
+        payloadDigest: request.payloadDigest,
+        expectedContentDigest: request.expectedContentDigest,
+        bindingDigest: request.bindingDigest,
+        inputDigest: request.inputDigest,
+        artifactDigests: [...request.artifactDigests],
+        idempotencyKey: request.idempotencyKey,
+        publishedContentDigest: input.publishedContentDigest,
+        readBackContentDigest: input.readBackContentDigest,
+        status: "verified",
+        verifiedAt: input.verifiedAt,
+    });
+}
+async function reconciliationRequired(input) {
+    return persistAction({
+        ...input,
+        eventType: "external-action.reconciliation-required",
+        suffix: "reconciliation-required",
+        operationInput: { reason: "provider outcome unknown after dispatch", requiredAt: input.now },
+        update: (current) => {
+            if (current.status === "reconciliation_required")
+                return current;
+            if (current.status !== "executing" || current.dispatch !== "sent_or_unknown") {
+                throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_STATE_TRANSITION_INVALID", "只有可能已发送的 executing 动作需要协调恢复。");
+            }
+            return transitionExternalAction(current, {
+                status: "reconciliation_required",
+                request: current.request,
+                grant: current.grant,
+                reason: "provider outcome unknown after dispatch",
+                requiredAt: input.now,
+            });
+        },
+    });
+}
+export async function executeExternalAction(input) {
+    const applicationState = await loadApplicationState(input.root, input.workItemId);
+    let current = currentAction(applicationState.projection, input.requestId);
+    if (current.status === "verified")
+        return current;
+    assertActiveAttempt(await readControlPlane(input.root, input.workItemId), current.request, new Date(input.now));
+    if (current.status === "reconciliation_required")
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_RECONCILIATION_REQUIRED", "外部动作结果未知，禁止自动重发。");
+    if (current.status === "failed" || current.status === "prepared")
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_STATE_TRANSITION_INVALID", "外部动作尚未获得有效 Grant 或已失败。");
+    if (canonicalDigest(input.payload) !== current.request.payloadDigest) {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_PAYLOAD_MISMATCH", "执行 payload 与批准摘要不一致。");
+    }
+    assertGrantAuthorizes(current.request, current.grant, new Date(input.now));
+    const executionOwner = `external-execution-${crypto.randomUUID()}`;
+    if (current.status === "approved" || (current.status === "executing" && current.dispatch === "not_sent")) {
+        const claimed = await mutateControlPlane({
+            cwd: input.root,
+            workItemId: input.workItemId,
+            eventType: "external-action.executing",
+            idempotencyKey: `external-action:execution-owner:${input.requestId}:${executionOwner}`,
+            actor: "external-coordinator",
+            stageId: current.request.stepId,
+            attemptId: current.request.attemptId,
+            operationInput: { executionOwner, startedAt: input.now },
+            mutate: async (projection) => {
+                const action = currentAction(projection, input.requestId);
+                if (action.status === "executing" && action.dispatch === "not_sent" && action.executionOwner !== undefined) {
+                    return { projection, value: { action, owned: false } };
+                }
+                if (action.status !== "approved" && (action.status !== "executing" || action.dispatch !== "not_sent")) {
+                    return { projection, value: { action, owned: false } };
+                }
+                assertActiveAttempt(projection, action.request, new Date(input.now));
+                await assertCurrentExternalActionContext(applicationState, projection, action.request);
+                const executing = action.status === "approved"
+                    ? transitionExternalAction(action, {
+                        status: "executing", request: action.request, grant: action.grant, dispatch: "not_sent",
+                        startedAt: input.now, executionOwner,
+                    })
+                    : { ...action, startedAt: input.now, executionOwner };
+                return {
+                    projection: { ...projection, externalActions: { ...projection.externalActions, [input.requestId]: executing } },
+                    value: { action: executing, owned: true },
+                };
+            },
+        });
+        current = claimed.action;
+        if (!claimed.owned)
+            return current;
+    }
+    if (current.status !== "executing" || current.dispatch !== "not_sent" || current.executionOwner !== executionOwner) {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_RECONCILIATION_REQUIRED", "外部动作可能已发送，禁止自动重发。");
+    }
+    const executionProjection = await readControlPlane(input.root, input.workItemId);
+    assertActiveAttempt(executionProjection, current.request, new Date(input.now));
+    await assertCurrentExternalActionContext(applicationState, executionProjection, current.request);
+    let dispatched = false;
+    const markDispatched = async () => {
+        const dispatchedState = await persistAction({
+            ...input,
+            eventType: "external-action.dispatched",
+            suffix: "dispatched",
+            operationInput: { dispatchedAt: input.now },
+            update: (action) => {
+                if (action.status !== "executing" || action.dispatch !== "not_sent" || action.executionOwner !== executionOwner) {
+                    throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_STATE_TRANSITION_INVALID", "外部动作 dispatch 边界重复或无效。");
+                }
+                return transitionExternalAction(action, { ...action, dispatch: "sent_or_unknown", dispatchedAt: input.now });
+            },
+        });
+        dispatched = dispatchedState.status === "executing" && dispatchedState.dispatch === "sent_or_unknown";
+    };
+    let readBack;
+    try {
+        readBack = await input.executor.execute({ root: input.root, request: current.request, grant: current.grant, payload: input.payload, markDispatched });
+    }
+    catch (error) {
+        const stored = currentAction(await readControlPlane(input.root, input.workItemId), input.requestId);
+        if (dispatched || (stored.status === "executing" && stored.dispatch === "sent_or_unknown")) {
+            return reconciliationRequired(input);
+        }
+        await persistAction({
+            ...input,
+            eventType: "external-action.executing",
+            suffix: `execution-owner-released:${executionOwner}`,
+            operationInput: { releasedAt: input.now },
+            update: (action) => {
+                if (action.status !== "executing" || action.dispatch !== "not_sent" || action.executionOwner !== executionOwner)
+                    return action;
+                const { executionOwner: _released, ...released } = action;
+                return released;
+            },
+        });
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_PROVIDER_EXECUTION_FAILED", "Provider 在 dispatch 前失败，未确认任何外部写入。");
+    }
+    const stored = currentAction(await readControlPlane(input.root, input.workItemId), input.requestId);
+    if (!dispatched || stored.status !== "executing" || stored.dispatch !== "sent_or_unknown") {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_DISPATCH_EVIDENCE_MISSING", "Provider 未记录 dispatch 边界，不能确认执行结果。");
+    }
+    let confirmed;
+    try {
+        confirmed = receipt(stored.request, stored.grant, readBack);
+    }
+    catch {
+        return reconciliationRequired(input);
+    }
+    return persistAction({
+        ...input,
+        eventType: "external-action.verified",
+        suffix: "verified",
+        operationInput: confirmed,
+        update: (action) => {
+            if (action.status !== "executing" || action.dispatch !== "sent_or_unknown" || action.executionOwner !== executionOwner)
+                throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_STATE_TRANSITION_INVALID", "只有 dispatch owner 的 executing 动作可被验证。");
+            return transitionExternalAction(action, { status: "verified", request: action.request, grant: action.grant, receipt: confirmed });
+        },
+    });
+}
+export async function reconcileExternalAction(input) {
+    const current = currentAction(await readControlPlane(input.root, input.workItemId), input.requestId);
+    if (current.status === "verified" || current.status === "failed")
+        return current;
+    if (current.status !== "reconciliation_required")
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_RECONCILIATION_NOT_REQUIRED", "当前外部动作不允许协调回查。");
+    let readBack;
+    try {
+        readBack = await input.executor.reconcile({ root: input.root, request: current.request, grant: current.grant });
+    }
+    catch {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_PROVIDER_RECONCILIATION_FAILED", "Provider 只读协调回查失败，未改变外部动作状态。");
+    }
+    if (readBack.outcome === "unknown") {
+        const safeReadBack = { outcome: "unknown", checkedAt: input.now };
+        return persistAction({
+            ...input,
+            eventType: "external-action.reconciled",
+            suffix: `reconciled-unknown:${canonicalDigest(safeReadBack).slice("sha256:".length)}`,
+            operationInput: safeReadBack,
+            update: (action) => action.status !== "reconciliation_required" ? action : { ...action, lastCheckedAt: input.now },
+        });
+    }
+    if (readBack.outcome === "failed") {
+        const safeReadBack = { outcome: "failed", checkedAt: input.now };
+        return persistAction({
+            ...input,
+            eventType: "external-action.reconciled",
+            suffix: `reconciled-failed:${canonicalDigest(safeReadBack).slice("sha256:".length)}`,
+            operationInput: safeReadBack,
+            update: (action) => {
+                if (action.status !== "reconciliation_required")
+                    throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_STATE_TRANSITION_INVALID", "协调失败结果需要 reconciliation_required 状态。");
+                return transitionExternalAction(action, {
+                    status: "failed",
+                    request: action.request,
+                    grant: action.grant,
+                    reason: "provider read-back did not verify approved content",
+                    failedAt: input.now,
+                });
+            },
+        });
+    }
+    let confirmed;
+    try {
+        confirmed = receipt(current.request, current.grant, {
+            targetStableId: readBack.targetStableId,
+            publishedContentDigest: readBack.contentDigest,
+            readBackContentDigest: readBack.contentDigest,
+            verifiedAt: input.now,
+        });
+    }
+    catch {
+        return persistAction({
+            ...input,
+            eventType: "external-action.reconciled",
+            suffix: `reconciled-mismatch:${canonicalDigest({ outcome: "unknown", checkedAt: input.now }).slice("sha256:".length)}`,
+            operationInput: { outcome: "unknown", checkedAt: input.now },
+            update: (action) => action.status !== "reconciliation_required" ? action : { ...action, lastCheckedAt: input.now },
+        });
+    }
+    return persistAction({
+        ...input,
+        eventType: "external-action.reconciled",
+        suffix: `reconciled-verified:${canonicalDigest(confirmed).slice("sha256:".length)}`,
+        operationInput: confirmed,
+        update: (action) => {
+            if (action.status !== "reconciliation_required")
+                throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_STATE_TRANSITION_INVALID", "协调确认需要 reconciliation_required 状态。");
+            return transitionExternalAction(action, { status: "verified", request: action.request, grant: action.grant, receipt: confirmed });
+        },
+    });
+}
+export async function markExternalActionFailed(input) {
+    if (input.terminal.isTTY !== true) {
+        throw new ExternalAuthorizationError("WSSPEC_INTERACTIVE_TTY_REQUIRED", "协调恢复决定必须来自真实交互式 TTY。");
+    }
+    if (input.evidence.trim() === "" || input.evidence.includes("\0")) {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_RECONCILIATION_EVIDENCE_INVALID", "协调恢复证据不能为空。");
+    }
+    const applicationState = await loadApplicationState(input.root, input.workItemId);
+    const initial = currentAction(applicationState.projection, input.requestId);
+    if (initial.request.requestDigest !== input.expectedRequestDigest) {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_REQUEST_DIGEST_MISMATCH", "协调恢复决定未绑定当前 Request 摘要。");
+    }
+    const evidenceDigest = canonicalDigest({ evidence: input.evidence }, "WSSPEC_EXTERNAL_RECONCILIATION_EVIDENCE_INVALID");
+    return persistAction({
+        root: input.root,
+        workItemId: input.workItemId,
+        requestId: input.requestId,
+        eventType: "external-action.reconciled",
+        suffix: `operator-mark-failed:${evidenceDigest.slice("sha256:".length)}`,
+        actor: input.actor,
+        operationInput: {
+            decision: "mark_failed",
+            requestDigest: input.expectedRequestDigest,
+            evidenceDigest,
+            actor: input.actor,
+        },
+        update: (action, projection) => {
+            if (action.status !== "reconciliation_required") {
+                throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_RECONCILIATION_NOT_REQUIRED", "当前外部动作不允许协调恢复决定。");
+            }
+            assertActiveAttempt(projection, action.request, new Date(input.now));
+            return transitionExternalAction(action, {
+                status: "failed",
+                request: action.request,
+                grant: action.grant,
+                reason: "操作者经审计决定将未知写入标记为失败",
+                failedAt: input.now,
+            });
+        },
+    });
+}
+export async function adoptVerifiedExternalAction(input) {
+    if (input.terminal.isTTY !== true) {
+        throw new ExternalAuthorizationError("WSSPEC_INTERACTIVE_TTY_REQUIRED", "协调恢复决定必须来自真实交互式 TTY。");
+    }
+    if (input.evidence.trim() === "" || input.evidence.includes("\0") || Buffer.byteLength(input.evidence, "utf8") > 2_048) {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_RECONCILIATION_EVIDENCE_INVALID", "协调恢复证据不能为空。");
+    }
+    const inspectedId = inspectDecodedCredentialSurface(input.externalStableId, {
+        detectCredentialKeys: true,
+        maximumBytes: 2_048,
+        maximumDecodeRounds: 4,
+    });
+    if (!inspectedId.ok || input.externalStableId.trim() === ""
+        || Buffer.byteLength(input.externalStableId, "utf8") > 2_048 || input.externalStableId.includes("\0")) {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_RECONCILIATION_EVIDENCE_INVALID", "外部稳定标识无效。");
+    }
+    const applicationState = await loadApplicationState(input.root, input.workItemId);
+    const initial = currentAction(applicationState.projection, input.requestId);
+    if (initial.request.requestDigest !== input.expectedRequestDigest) {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_REQUEST_DIGEST_MISMATCH", "协调恢复决定未绑定当前 Request 摘要。");
+    }
+    if (input.contentDigest !== initial.request.expectedContentDigest) {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_READBACK_MISMATCH", "待采纳内容摘要与批准内容不一致。");
+    }
+    if (input.executor.adopt === undefined) {
+        throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_ADOPTION_UNSUPPORTED", "当前 Provider 不支持带稳定标识的权威回读采纳。");
+    }
+    const evidenceDigest = canonicalDigest({ evidence: input.evidence }, "WSSPEC_EXTERNAL_RECONCILIATION_EVIDENCE_INVALID");
+    return persistAction({
+        root: input.root,
+        workItemId: input.workItemId,
+        requestId: input.requestId,
+        eventType: "external-action.reconciled",
+        suffix: `operator-adopt-verified:${canonicalDigest({ externalStableId: input.externalStableId, contentDigest: input.contentDigest, evidenceDigest }).slice("sha256:".length)}`,
+        actor: input.actor,
+        operationInput: {
+            decision: "adopt_verified",
+            requestDigest: input.expectedRequestDigest,
+            externalStableId: input.externalStableId,
+            contentDigest: input.contentDigest,
+            evidenceDigest,
+            actor: input.actor,
+        },
+        update: async (action, projection) => {
+            if (action.status !== "reconciliation_required") {
+                throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_RECONCILIATION_NOT_REQUIRED", "当前外部动作不允许协调恢复决定。");
+            }
+            if (action.request.requestDigest !== input.expectedRequestDigest) {
+                throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_REQUEST_DIGEST_MISMATCH", "协调恢复决定未绑定当前 Request 摘要。");
+            }
+            assertActiveAttempt(projection, action.request, new Date(input.now));
+            await assertCurrentExternalActionContext(applicationState, projection, action.request);
+            let readBack;
+            try {
+                readBack = await input.executor.adopt({
+                    root: input.root,
+                    request: action.request,
+                    grant: action.grant,
+                    externalStableId: input.externalStableId,
+                    contentDigest: input.contentDigest,
+                });
+            }
+            catch {
+                throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_PROVIDER_RECONCILIATION_FAILED", "Provider 权威只读回查失败，未改变外部动作状态。");
+            }
+            if (readBack.outcome !== "verified") {
+                throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_ADOPTION_NOT_VERIFIED", "Provider 未能权威确认待采纳外部动作。");
+            }
+            if (readBack.targetStableId !== input.externalStableId || readBack.contentDigest !== input.contentDigest) {
+                throw new ExternalAuthorizationError("WSSPEC_EXTERNAL_READBACK_MISMATCH", "Provider 权威回读与待采纳稳定标识或内容摘要不一致。");
+            }
+            const confirmed = receipt(action.request, action.grant, {
+                targetStableId: action.request.target.stableId,
+                ...(action.request.externalEffectKind === "issue.comment" ? { externalEffectId: input.externalStableId } : {}),
+                publishedContentDigest: input.contentDigest,
+                readBackContentDigest: readBack.contentDigest,
+                verifiedAt: input.now,
+            });
+            return transitionExternalAction(action, {
+                status: "verified",
+                request: action.request,
+                grant: action.grant,
+                receipt: confirmed,
+            });
+        },
+    });
+}
+//# sourceMappingURL=external-action.js.map