@ai-agent-forge/plugin-workflow 0.85.20

package/dist/engine.js

@@ -0,0 +1,925 @@
+/**
+ * Workflow advance engine: pure state-machine derivation over WorkflowState
+ * (§5 of docs/design/工作流编排插件设计.md).
+ *
+ * Everything here is deterministic and derived from the persisted snapshot
+ * plus a plan-lookup callback: no clocks, no CapabilityAPI access — index.ts
+ * owns persistence (§5 总则 1 snapshot-driven reevaluation; events are only
+ * trigger signals, the truth always comes from the current branch entries).
+ * Every conversion appends exactly one transition; held/rejected activation
+ * attempts are audited too, deduplicated when the previous transition for the
+ * stage already carries the same held code and unchanged wait condition
+ * (§5 总则 5).
+ *
+ * Budget note (§5 总则 4): the per-workflow cascade limit
+ * (max(32, 2 x stageCount), recomputed per run from the workflow's current
+ * stage count — see cascadeLimitFor) covers every transition of one run —
+ * the explicit action's own conversions plus the derived reevaluation chain.
+ * Logical operations reserve their maximum
+ * bump count up front (canBump) so a mid-chain stop never leaves a mutated
+ * status without its audit entry; hitting the cap is not terminal — any
+ * workflow_advance action resumes the chain.
+ */
+export const DEFAULT_RETRY_LIMIT = 2;
+export const DEFAULT_MAX_RETREATS = 3;
+export const DEFAULT_MAX_ACTIVE_STAGES = 4;
+const DEFAULT_CASCADE_LIMIT = 32;
+const DIAGNOSTICS_CAP = 50;
+export function cascadeLimitFor(workflow) {
+    return Math.max(DEFAULT_CASCADE_LIMIT, 2 * workflow.stages.length);
+}
+// ---------------------------------------------------------------------------
+// Small lookups
+// ---------------------------------------------------------------------------
+function runtimeOf(workflow, stageId) {
+    return workflow.runtime.find((item) => item.stageId === stageId);
+}
+function specOf(workflow, stageId) {
+    return workflow.stages.find((item) => item.id === stageId);
+}
+function retryLimitOf(spec) {
+    return spec.retryLimit ?? DEFAULT_RETRY_LIMIT;
+}
+export function maxRetreatsOf(workflow) {
+    return workflow.maxRetreats ?? DEFAULT_MAX_RETREATS;
+}
+export function maxActiveOf(workflow) {
+    return workflow.maxActiveStages ?? DEFAULT_MAX_ACTIVE_STAGES;
+}
+function activeCount(workflow) {
+    return workflow.runtime.filter((item) => item.status === "active").length;
+}
+function uncoveredAcceptanceIds(spec, runtime) {
+    const covered = new Set(runtime.evidence.map((item) => item.acceptanceId));
+    return spec.objective.acceptance.map((item) => item.id).filter((id) => !covered.has(id));
+}
+function pushDiagnostic(workflow, text) {
+    if (workflow.diagnostics.length >= DIAGNOSTICS_CAP)
+        workflow.diagnostics.shift();
+    workflow.diagnostics.push(text);
+}
+const stageKey = (workflowId, stageId) => `${workflowId}::${stageId}`;
+function newWorkflowRun(workflow, deps, closures) {
+    return { workflow, deps, limit: cascadeLimitFor(workflow), used: 0, transitions: [], closures, hitLimit: false };
+}
+/** Reserves `needed` transition slots so an operation never mutates without its audit entry. */
+function canBump(run, needed) {
+    if (run.used + needed <= run.limit)
+        return true;
+    run.hitLimit = true;
+    return false;
+}
+function appendTransition(run, stageId, from, to, trigger, reason) {
+    if (run.used >= run.limit) {
+        run.hitLimit = true;
+        return false;
+    }
+    run.workflow.revision += 1;
+    run.transitions.push({
+        workflowId: run.workflow.id,
+        ...(stageId !== undefined ? { stageId } : {}),
+        from,
+        to,
+        trigger,
+        reason,
+        revision: run.workflow.revision,
+    });
+    run.used += 1;
+    if (stageId !== undefined) {
+        run.deps.lastStageTransition.set(stageKey(run.workflow.id, stageId), {
+            code: reason.code,
+            detail: reason.detail,
+        });
+    }
+    return true;
+}
+/**
+ * A held (not activated) pending stage: appends the held transition unless
+ * the stage's previous transition already carries the same held code and
+ * unchanged wait condition (§5 总则 5 dedup — reevaluation becomes a no-op).
+ * plan-dangling and write-scope-conflict additionally raise a diagnostic
+ * (§5 总则 2 conditions b/d); deps-incomplete and active-limit are normal
+ * graph waiting and stay transition-only.
+ */
+function holdStage(run, stageId, trigger, code, message, detail) {
+    const key = stageKey(run.workflow.id, stageId);
+    const last = run.deps.lastStageTransition.get(key);
+    if (last !== undefined && last.code === code && last.detail === detail)
+        return false;
+    const runtime = runtimeOf(run.workflow, stageId);
+    const from = runtime?.status ?? "pending";
+    if (!appendTransition(run, stageId, from, from, trigger, { code, message, detail }))
+        return false;
+    if (code === "stage.activated.held-plan-dangling" || code === "stage.held.write-scope-conflict") {
+        pushDiagnostic(run.workflow, message);
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Scope guards (§5 总则 2 condition d)
+// ---------------------------------------------------------------------------
+/**
+ * An undeclared (or empty) scope on a write stage is global: it intersects
+ * every other write stage. Read stages are never scope-checked.
+ */
+function scopesIntersect(a, b) {
+    if (a === undefined || a.length === 0 || b === undefined || b.length === 0)
+        return true;
+    return a.some((tag) => b.includes(tag));
+}
+function findWriteConflict(workflow, spec) {
+    return workflow.stages.find((other) => {
+        if (other.id === spec.id || other.kind !== "write")
+            return false;
+        return runtimeOf(workflow, other.id)?.status === "active" && scopesIntersect(spec.scope, other.scope);
+    });
+}
+/** Every stage that transitively depends on `stageId` (reverse dependsOn reachability). */
+function transitiveDependents(workflow, stageId) {
+    const dependents = new Set();
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const spec of workflow.stages) {
+            if (dependents.has(spec.id))
+                continue;
+            if (spec.dependsOn.some((dep) => dep === stageId || dependents.has(dep))) {
+                dependents.add(spec.id);
+                grew = true;
+            }
+        }
+    }
+    return [...dependents];
+}
+// ---------------------------------------------------------------------------
+// Evaluation (§5 rule 3) and failure disposal (§5 rule 5)
+// ---------------------------------------------------------------------------
+/** Settlement of a passed evaluation: auto -> completed, review -> awaiting_review. */
+function settlePassedStage(run, spec, runtime, trigger) {
+    const from = runtime.status;
+    if (spec.advance === "review") {
+        runtime.status = "awaiting_review";
+        // §5 rule 3: awaiting_review does not count as completed — dependents stay locked.
+        return appendTransition(run, spec.id, from, "awaiting_review", trigger, {
+            code: "stage.awaiting-review",
+            message: `stage ${spec.id} passed evaluation and awaits review`,
+        })
+            ? 1
+            : 0;
+    }
+    runtime.status = "completed";
+    const covered = spec.objective.acceptance.length > 0;
+    return appendTransition(run, spec.id, from, "completed", trigger, {
+        code: covered ? "stage.completed.acceptance-covered" : "stage.completed",
+        message: `stage ${spec.id} completed (${covered ? "acceptance covered" : "plan lower bound"})`,
+    })
+        ? 1
+        : 0;
+}
+/**
+ * §5 rule 3 objective evaluation of one ACTIVE stage against its plan: the
+ * lower bound is the completed plan's own evidence; declared acceptance adds
+ * per-item evidence coverage. Cancelled plan or unmet evaluation -> rule 5
+ * failure disposal.
+ */
+function evaluateActiveStage(run, spec, runtime, trigger) {
+    if (spec.planId === undefined)
+        return 0; // checkpoint stages settle via the explicit complete action
+    const plan = run.deps.getPlan(spec.planId);
+    if (plan === undefined)
+        return 0; // unresolvable after activation (plans are append-only); nothing to evaluate
+    if (plan.status === "cancelled") {
+        return failStage(run, spec, runtime, trigger, "stage.failed.plan-cancelled", `plan ${spec.planId} is cancelled`);
+    }
+    if (plan.status !== "completed")
+        return 0; // waiting: plan-incomplete
+    const missing = uncoveredAcceptanceIds(spec, runtime);
+    const lowerBoundUnmet = spec.objective.acceptance.length === 0 && plan.evidence.length === 0;
+    if (missing.length > 0 || lowerBoundUnmet) {
+        return failStage(run, spec, runtime, trigger, "stage.failed.acceptance-missing", `missing acceptance: [${missing.join(", ")}]${lowerBoundUnmet ? " (plan evidence empty)" : ""}`);
+    }
+    return settlePassedStage(run, spec, runtime, trigger);
+}
+/**
+ * §5 rule 5 failure disposal: the stage transition to failed is audited, then
+ * either in-place retry (evidence retained, attempts + 1), cross-stage
+ * retreat via the stage's onFail edge (when retries are exhausted and onFail
+ * is declared), or workflow failure. A failed workflow keeps every stage in
+ * its current state — no forced settlement (rule 5, contrast with cancel).
+ */
+function failStage(run, spec, runtime, trigger, code, detail) {
+    if (!canBump(run, 2))
+        return 0; // failure transition + one disposal transition
+    const from = runtime.status;
+    runtime.status = "failed";
+    const appended = appendTransition(run, spec.id, from, "failed", trigger, {
+        code,
+        message: `stage ${spec.id} failed`,
+        detail,
+    })
+        ? 1
+        : 0;
+    pushDiagnostic(run.workflow, `stage ${spec.id} failed: ${detail}`);
+    runtime.attempts += 1;
+    if (runtime.attempts > retryLimitOf(spec)) {
+        if (spec.onFail !== undefined) {
+            const target = specOf(run.workflow, spec.onFail);
+            if (target !== undefined)
+                return appended + crossStageRetreat(run, target, trigger, `stage ${spec.id} exhausted retries`, spec);
+        }
+        const message = `workflow failed: stage ${spec.id} exhausted retry limit ${retryLimitOf(spec)}`;
+        pushDiagnostic(run.workflow, message);
+        run.workflow.status = "failed";
+        return appendTransition(run, undefined, "running", "failed", trigger, {
+            code: "workflow.failed.stage-retries",
+            message,
+            detail: `stage:${spec.id}`,
+        })
+            ? appended + 1
+            : appended;
+    }
+    runtime.status = "pending";
+    return appendTransition(run, spec.id, "failed", "pending", trigger, {
+        code: "stage.retry.queued",
+        message: `stage ${spec.id} queued for in-place retry (attempt ${runtime.attempts}/${retryLimitOf(spec)}); evidence retained`,
+    })
+        ? appended + 1
+        : appended;
+}
+/**
+ * §5 rule 5 cross-stage retreat (explicit onFail, retreat, or reject): the
+ * retreat budget is checked first — over budget the workflow fails and the
+ * scene is preserved as-is; otherwise the target resets to pending
+ * unconditionally (a retry-waiting target loses its evidence too) and every
+ * non-pending transitive dependent resets to pending with evidence cleared
+ * (their inputs are invalidated — DAG propagation). The failing/rejected
+ * `origin` stage itself always resets as well (rule 5 is unconditional): when
+ * the onFail target sits on a parallel branch the origin is outside the
+ * dependent closure and joins the reset set explicitly. attempts are
+ * retained (§4); `skipped` dependents never reset (explicit scope ruling).
+ */
+function crossStageRetreat(run, target, trigger, note, origin) {
+    const dependents = transitiveDependents(run.workflow, target.id);
+    const originOutside = origin !== undefined && origin.id !== target.id && !dependents.includes(origin.id);
+    // Retreat audit transition (+ at most one more disposal transition when the
+    // origin sits outside the dependent closure and needs its own audit slot).
+    if (!canBump(run, originOutside ? 2 : 1))
+        return 0;
+    run.workflow.retreatCount += 1;
+    if (run.workflow.retreatCount > maxRetreatsOf(run.workflow)) {
+        const message = `workflow failed: retreat budget exhausted (${run.workflow.retreatCount}/${maxRetreatsOf(run.workflow)})`;
+        pushDiagnostic(run.workflow, `${message} — ${note}`);
+        run.workflow.status = "failed";
+        return appendTransition(run, undefined, "running", "failed", trigger, {
+            code: "workflow.failed.retreat-budget",
+            message,
+            detail: note,
+        })
+            ? 1
+            : 0;
+    }
+    const targetFrom = runtimeOf(run.workflow, target.id)?.status ?? "pending";
+    const resetIds = [];
+    for (const stageId of [target.id, ...(originOutside ? [origin.id] : []), ...dependents]) {
+        const runtime = runtimeOf(run.workflow, stageId);
+        if (runtime === undefined)
+            continue;
+        if (stageId === target.id ||
+            stageId === origin?.id ||
+            runtime.status === "completed" ||
+            runtime.status === "active" ||
+            runtime.status === "awaiting_review" ||
+            runtime.status === "failed") {
+            runtime.status = "pending";
+            runtime.evidence = [];
+            resetIds.push(stageId);
+        }
+    }
+    const detail = `target:${target.id} reset:[${resetIds.join(", ")}]${note !== "" ? ` — ${note}` : ""}`;
+    return appendTransition(run, target.id, targetFrom, "pending", trigger, {
+        code: "stage.retreated",
+        message: `retreat to stage ${target.id}: reset [${resetIds.join(", ")}]`,
+        detail,
+    })
+        ? 1
+        : 0;
+}
+// ---------------------------------------------------------------------------
+// Activation scan (§5 总则 2) and the reevaluation loop (§5 总则 1)
+// ---------------------------------------------------------------------------
+/**
+ * One activation pass over pending stages in declaration order. A pending
+ * stage activates only when (a) dependsOn are all completed/skipped (skip
+ * counts as completed for unlocking — §5 rule 6), (b) its planId resolves in
+ * the current branch entries, (c) the active count is below the cap, (d) a
+ * write stage's scope does not intersect an active write stage, and (e)
+ * attempts === 0 — retry-waiting stages never auto-activate (anti
+ * burnout-spiral, §5 总则 2 e). Each freshly activated stage is immediately
+ * re-evaluated once (§5 rule 2), which covers "plan already completed at
+ * activation" and pure-checkpoint restore flows.
+ */
+function activationPass(run, trigger) {
+    let appended = 0;
+    for (const spec of run.workflow.stages) {
+        const runtime = runtimeOf(run.workflow, spec.id);
+        if (runtime === undefined || runtime.status !== "pending" || runtime.attempts !== 0)
+            continue; // (e)
+        const incomplete = spec.dependsOn.filter((dep) => {
+            const dependency = runtimeOf(run.workflow, dep);
+            return !(dependency !== undefined && (dependency.status === "completed" || dependency.status === "skipped"));
+        });
+        if (incomplete.length > 0) {
+            if (holdStage(run, spec.id, trigger, "stage.held.deps-incomplete", `stage ${spec.id} waiting: dependencies incomplete [${incomplete.join(", ")}]`, `missing:[${incomplete.join(", ")}]`)) {
+                appended += 1;
+            }
+            continue;
+        }
+        if (spec.planId !== undefined && run.deps.getPlan(spec.planId) === undefined) {
+            if (holdStage(run, spec.id, trigger, "stage.activated.held-plan-dangling", `stage ${spec.id} held: plan ${spec.planId} not found in the session branch`, `plan:${spec.planId}`)) {
+                appended += 1;
+            }
+            continue;
+        }
+        if (activeCount(run.workflow) >= maxActiveOf(run.workflow)) {
+            if (holdStage(run, spec.id, trigger, "stage.held.active-limit", `stage ${spec.id} waiting: active stage limit (${maxActiveOf(run.workflow)}) reached`, `limit:${maxActiveOf(run.workflow)}`)) {
+                appended += 1;
+            }
+            continue;
+        }
+        if (spec.kind === "write") {
+            const conflict = findWriteConflict(run.workflow, spec);
+            if (conflict !== undefined) {
+                const own = spec.scope === undefined || spec.scope.length === 0 ? "global" : spec.scope.join(",");
+                const other = conflict.scope === undefined || conflict.scope.length === 0 ? "global" : conflict.scope.join(",");
+                if (holdStage(run, spec.id, trigger, "stage.held.write-scope-conflict", `stage ${spec.id} blocked: write scope [${own}] intersects active stage ${conflict.id} scope [${other}]`, `conflict:${conflict.id} scope:[${own}] vs [${other}]`)) {
+                    appended += 1;
+                }
+                continue;
+            }
+        }
+        if (!canBump(run, 3))
+            break; // activation + immediate evaluation chain (worst case 2 more)
+        runtime.status = "active";
+        if (appendTransition(run, spec.id, "pending", "active", trigger, {
+            code: "stage.activated",
+            message: `stage ${spec.id} activated`,
+        })) {
+            appended += 1;
+        }
+        // §5 rule 2: immediate single-stage snapshot reevaluation of the activated stage.
+        appended += evaluateActiveStage(run, spec, runtime, "activation-reeval");
+    }
+    return appended;
+}
+/** §5 rule 7 closure: all stages completed/skipped -> workflow completed, closure evidence recorded. */
+function checkClosure(run, trigger) {
+    if (run.workflow.status !== "running")
+        return 0;
+    if (!run.workflow.runtime.every((item) => item.status === "completed" || item.status === "skipped"))
+        return 0;
+    if (!canBump(run, 1))
+        return 0;
+    run.workflow.status = "completed";
+    const evidence = run.workflow.runtime
+        .filter((item) => item.status === "completed")
+        .flatMap((item) => item.evidence.map((entry) => ({ stageId: item.stageId, acceptanceId: entry.acceptanceId, ref: entry.ref })));
+    run.closures.push({
+        workflowId: run.workflow.id,
+        ...(run.workflow.goalId !== undefined ? { goalId: run.workflow.goalId } : {}),
+        evidence,
+    });
+    return appendTransition(run, undefined, "running", "completed", trigger, {
+        code: "workflow.completed",
+        message: `workflow completed: all ${run.workflow.stages.length} stage(s) settled`,
+        detail: `evidence items: ${evidence.length}`,
+    })
+        ? 1
+        : 0;
+}
+/** §5 总则 4: the cascade marker is appended beyond the budget by design (it is the stop record, not a chain step). */
+function markCascadeLimit(run, trigger) {
+    const message = `cascade limit ${run.limit} reached; transitions stopped — resumable via any workflow_advance action`;
+    pushDiagnostic(run.workflow, message);
+    run.workflow.revision += 1;
+    run.transitions.push({
+        workflowId: run.workflow.id,
+        from: run.workflow.status,
+        to: run.workflow.status,
+        trigger,
+        reason: { code: "cascade.limit-reached", message },
+        revision: run.workflow.revision,
+    });
+}
+/**
+ * The reevaluation loop for one running workflow: evaluate active stages ->
+ * scan activation -> check closure, repeating to a fixed point (no new
+ * persisted transitions). Condition-not-met passes are idempotent no-ops;
+ * the held dedup keeps repeat passes audit-silent (§5 总则 1 / 总则 5).
+ */
+function reevaluateWorkflow(run, trigger) {
+    while (run.workflow.status === "running") {
+        if (run.used >= run.limit) {
+            run.hitLimit = true;
+            break;
+        }
+        let appended = 0;
+        for (const spec of run.workflow.stages) {
+            const runtime = runtimeOf(run.workflow, spec.id);
+            if (runtime === undefined || runtime.status !== "active")
+                continue;
+            if (!canBump(run, 2))
+                break;
+            appended += evaluateActiveStage(run, spec, runtime, trigger);
+        }
+        if (run.hitLimit)
+            break;
+        appended += activationPass(run, trigger);
+        if (run.hitLimit)
+            break;
+        appended += checkClosure(run, trigger);
+        if (run.hitLimit)
+            break;
+        if (appended === 0)
+            return; // fixed point
+    }
+    if (run.hitLimit)
+        markCascadeLimit(run, trigger);
+}
+/** Snapshot reevaluation over every workflow in the state (one budget per workflow per run). */
+export function reevaluateAll(state, deps, trigger) {
+    const workflows = state.workflows.map((workflow) => structuredClone(workflow));
+    const run = { state: { workflows }, transitions: [], cascadeLimitReached: false, closures: [] };
+    for (const workflow of workflows) {
+        if (workflow.status !== "running")
+            continue;
+        const workflowRun = newWorkflowRun(workflow, deps, run.closures);
+        reevaluateWorkflow(workflowRun, trigger);
+        run.transitions.push(...workflowRun.transitions);
+        if (workflowRun.hitLimit)
+            run.cascadeLimitReached = true;
+    }
+    return run;
+}
+// ---------------------------------------------------------------------------
+// workflow_set application (§6)
+// ---------------------------------------------------------------------------
+/**
+ * Applies a graded full-submit update: workflow-level fields, the new stage
+ * sequence (runtime aligned by stageId — existing runtimes are preserved,
+ * appended stages get fresh pending runtimes), evidence linkage pruning for
+ * removed acceptance ids, one stage.spec-amended transition per amended
+ * active/awaiting_review stage, then the post-change reevaluation chain
+ * (§5 总则 1: conversions settle -> same-call reevaluation).
+ */
+export function applyWorkflowSet(state, next, diff, deps) {
+    const workflows = state.workflows.map((workflow) => structuredClone(workflow));
+    const run = { state: { workflows }, transitions: [], cascadeLimitReached: false, closures: [] };
+    if (diff.created) {
+        workflows.push({
+            id: next.id,
+            title: next.title,
+            ...(next.goalId !== undefined ? { goalId: next.goalId } : {}),
+            status: "draft",
+            revision: next.revision,
+            stages: next.stages.map((stage) => structuredClone(stage)),
+            runtime: next.stages.map((stage) => ({ stageId: stage.id, status: "pending", attempts: 0, evidence: [] })),
+            retreatCount: 0,
+            ...(next.maxRetreats !== undefined ? { maxRetreats: next.maxRetreats } : {}),
+            ...(next.maxActiveStages !== undefined ? { maxActiveStages: next.maxActiveStages } : {}),
+            diagnostics: [],
+        });
+        return run;
+    }
+    const record = workflows.find((workflow) => workflow.id === next.id);
+    if (record === undefined)
+        throw new Error(`unknown workflow: ${next.id}`);
+    // Workflow-level fields are modifiable while running (§6), revision is the
+    // caller's monotonic value; engine conversions below increment past it.
+    record.title = next.title;
+    if (next.goalId === undefined)
+        delete record.goalId;
+    else
+        record.goalId = next.goalId;
+    if (next.maxRetreats === undefined)
+        delete record.maxRetreats;
+    else
+        record.maxRetreats = next.maxRetreats;
+    if (next.maxActiveStages === undefined)
+        delete record.maxActiveStages;
+    else
+        record.maxActiveStages = next.maxActiveStages;
+    record.revision = next.revision;
+    record.stages = next.stages.map((stage) => structuredClone(stage));
+    const previousRuntime = new Map(record.runtime.map((item) => [item.stageId, item]));
+    record.runtime = record.stages.map((spec) => previousRuntime.get(spec.id) ?? { stageId: spec.id, status: "pending", attempts: 0, evidence: [] });
+    // Evidence linkage (§6): an evidence item is dropped when its acceptanceId
+    // is non-empty and no longer references the amended acceptance set — this
+    // holds even when the amend emptied acceptance entirely, so no dead linkage
+    // survives a switch to lower-bound mode. Ref-only items (empty
+    // acceptanceId, checkpoint completion records) survive regardless of the
+    // spec shape.
+    for (const spec of record.stages) {
+        const runtime = runtimeOf(record, spec.id);
+        if (runtime === undefined || runtime.evidence.length === 0)
+            continue;
+        const ids = new Set(spec.objective.acceptance.map((item) => item.id));
+        runtime.evidence = runtime.evidence.filter((entry) => entry.acceptanceId === "" || ids.has(entry.acceptanceId));
+    }
+    const workflowRun = newWorkflowRun(record, deps, run.closures);
+    for (const change of diff.amendChanges) {
+        const runtime = runtimeOf(record, change.stageId);
+        const from = runtime?.status ?? "pending";
+        const detail = `fields:[${change.fields.join(", ")}] note:${change.amendNote}` +
+            (change.prunedEvidence.length > 0 ? ` pruned evidence for [${change.prunedEvidence.join(", ")}]` : "");
+        if (canBump(workflowRun, 1)) {
+            appendTransition(workflowRun, change.stageId, from, from, "tool", {
+                code: "stage.spec-amended",
+                message: `stage ${change.stageId} spec amended`,
+                detail,
+            });
+        }
+    }
+    if (record.status === "running")
+        reevaluateWorkflow(workflowRun, "tool");
+    run.transitions.push(...workflowRun.transitions);
+    if (workflowRun.hitLimit)
+        run.cascadeLimitReached = true;
+    return run;
+}
+// ---------------------------------------------------------------------------
+// workflow_advance application (§5 rule 6)
+// ---------------------------------------------------------------------------
+function requireStage(workflow, stageId) {
+    if (stageId === undefined)
+        throw new Error("stageId is required for this action");
+    const spec = specOf(workflow, stageId);
+    if (spec === undefined)
+        throw new Error(`unknown stage: ${stageId} (workflow ${workflow.id})`);
+    return spec;
+}
+function normalizeEvidence(items) {
+    return items.map((item) => ({ acceptanceId: item.acceptanceId ?? "", ref: item.ref }));
+}
+/**
+ * Applies one explicit workflow_advance action, then runs the post-action
+ * reevaluation chain (§5 总则 1). Illegal conversions throw structured
+ * errors (§5 rule 6) — index.ts surfaces them as tool errors unchanged.
+ */
+export function applyAdvance(state, input, deps) {
+    const workflows = state.workflows.map((workflow) => structuredClone(workflow));
+    const run = { state: { workflows }, transitions: [], cascadeLimitReached: false, closures: [] };
+    if (input.action === "inspect") {
+        // Read-only and allowed on every workflow status (§5 rule 6), but still
+        // scoped to one workflow: an unknown id is a structured error.
+        if (!workflows.some((workflow) => workflow.id === input.workflowId)) {
+            throw new Error(`unknown workflow: ${input.workflowId}`);
+        }
+        return run; // response decorations are added by the caller
+    }
+    const record = workflows.find((workflow) => workflow.id === input.workflowId);
+    if (record === undefined)
+        throw new Error(`unknown workflow: ${input.workflowId}`);
+    if (record.status === "completed" || record.status === "failed" || record.status === "cancelled") {
+        throw new Error(`workflow is ${record.status} and accepts no further actions: ${input.workflowId}`);
+    }
+    const workflowRun = newWorkflowRun(record, deps, run.closures);
+    const requireRunning = () => {
+        if (record.status !== "running") {
+            throw new Error(`workflow is ${record.status}; this action requires a running workflow`);
+        }
+    };
+    const noteSuffix = input.note !== undefined && input.note !== "" ? `: ${input.note}` : "";
+    switch (input.action) {
+        case "start": {
+            if (record.status !== "draft")
+                throw new Error(`workflow is already ${record.status}; start requires draft`);
+            if (!canBump(workflowRun, 1))
+                break;
+            const roots = record.stages.filter((spec) => spec.dependsOn.length === 0).length;
+            record.status = "running";
+            appendTransition(workflowRun, undefined, "draft", "running", "tool", {
+                code: "workflow.started",
+                message: `workflow started with ${roots} root stage(s)`,
+                detail: `roots:${roots}`,
+            });
+            break;
+        }
+        case "record-evidence": {
+            requireRunning();
+            const spec = requireStage(record, input.stageId);
+            const runtime = runtimeOf(record, spec.id);
+            if (runtime === undefined)
+                throw new Error(`unknown stage: ${spec.id}`);
+            if (runtime.status === "completed" || runtime.status === "skipped" || runtime.status === "failed") {
+                throw new Error(`stage ${spec.id} is ${runtime.status}; record-evidence accepts pending (retry wait), active, and awaiting_review stages`);
+            }
+            if (spec.objective.acceptance.length === 0) {
+                throw new Error(`stage ${spec.id} declares no acceptance (lower-bound mode); record-evidence does not apply — the plan's completion evidence is the lower bound`);
+            }
+            const items = input.evidence ?? [];
+            if (items.length === 0)
+                throw new Error("record-evidence requires at least one evidence item");
+            for (const item of items) {
+                if (item.acceptanceId === undefined || item.acceptanceId.trim() === "") {
+                    throw new Error(`stage ${spec.id}: evidence items must carry acceptanceId in acceptance mode`);
+                }
+                if (!spec.objective.acceptance.some((entry) => entry.id === item.acceptanceId)) {
+                    throw new Error(`stage ${spec.id}: acceptanceId ${item.acceptanceId} does not reference the current spec's acceptance`);
+                }
+            }
+            if (!canBump(workflowRun, 2))
+                break; // evidence.recorded + possible single-stage wake settlement
+            const from = runtime.status;
+            runtime.evidence = [...runtime.evidence, ...normalizeEvidence(items)];
+            appendTransition(workflowRun, spec.id, from, from, "tool", {
+                code: "evidence.recorded",
+                message: `stage ${spec.id}: recorded ${items.length} evidence item(s)`,
+                detail: items.map((item) => `${item.acceptanceId} <- ${item.ref}`).join("; "),
+            });
+            if (runtime.status === "pending" && runtime.attempts > 0) {
+                // §5 rule 4 exception — the only automatic wake channel for
+                // retry-waiting stages: a single-stage evaluation by the current
+                // spec and latest evidence. Pass -> settle (completion propagates
+                // through the reevaluation below); still missing -> keep waiting,
+                // no attempts consumed.
+                const plan = spec.planId !== undefined ? workflowRun.deps.getPlan(spec.planId) : undefined;
+                const passed = plan !== undefined &&
+                    plan.status === "completed" &&
+                    plan.evidence.length > 0 &&
+                    uncoveredAcceptanceIds(spec, runtime).length === 0;
+                if (passed)
+                    settlePassedStage(workflowRun, spec, runtime, "tool");
+            }
+            break;
+        }
+        case "approve": {
+            requireRunning();
+            const spec = requireStage(record, input.stageId);
+            const runtime = runtimeOf(record, spec.id);
+            if (runtime === undefined)
+                throw new Error(`unknown stage: ${spec.id}`);
+            if (runtime.status !== "awaiting_review") {
+                throw new Error(`stage ${spec.id} is ${runtime.status}; approve only settles awaiting_review stages`);
+            }
+            const items = input.evidence ?? [];
+            if (spec.objective.acceptance.length > 0) {
+                // Same strong validation as record-evidence/complete: in acceptance
+                // mode every carried evidence item must reference the current spec.
+                for (const item of items) {
+                    if (item.acceptanceId === undefined || item.acceptanceId.trim() === "") {
+                        throw new Error(`stage ${spec.id}: evidence items must carry acceptanceId in acceptance mode`);
+                    }
+                    if (!spec.objective.acceptance.some((entry) => entry.id === item.acceptanceId)) {
+                        throw new Error(`stage ${spec.id}: acceptanceId ${item.acceptanceId} does not reference the current spec's acceptance`);
+                    }
+                }
+            }
+            if (!canBump(workflowRun, 1))
+                break;
+            if (items.length > 0)
+                runtime.evidence = [...runtime.evidence, ...normalizeEvidence(items)];
+            runtime.status = "completed";
+            appendTransition(workflowRun, spec.id, "awaiting_review", "completed", "tool", {
+                code: spec.objective.acceptance.length > 0 ? "stage.completed.acceptance-covered" : "stage.completed",
+                message: `stage ${spec.id} approved in review`,
+                detail: input.note,
+            });
+            break;
+        }
+        case "reject": {
+            requireRunning();
+            const spec = requireStage(record, input.stageId);
+            const runtime = runtimeOf(record, spec.id);
+            if (runtime === undefined)
+                throw new Error(`unknown stage: ${spec.id}`);
+            if (runtime.status !== "awaiting_review") {
+                throw new Error(`stage ${spec.id} is ${runtime.status}; reject only applies to awaiting_review stages`);
+            }
+            if (spec.onFail !== undefined) {
+                // §5 rule 6: reject walks the stage's onFail edge; the rejected
+                // stage itself is the retreat origin and always resets (rule 5).
+                const target = requireStage(record, spec.onFail);
+                crossStageRetreat(workflowRun, target, "tool", `review rejection of stage ${spec.id}${noteSuffix}`, spec);
+            }
+            else {
+                // No onFail edge: in-place retry semantics (rule 6 / rule 5).
+                runtime.attempts += 1;
+                if (runtime.attempts > retryLimitOf(spec)) {
+                    const message = `workflow failed: stage ${spec.id} exhausted retry limit ${retryLimitOf(spec)} (rejected in review)`;
+                    if (canBump(workflowRun, 1)) {
+                        pushDiagnostic(record, message);
+                        record.status = "failed";
+                        appendTransition(workflowRun, undefined, "running", "failed", "tool", {
+                            code: "workflow.failed.stage-retries",
+                            message,
+                            detail: `stage:${spec.id}${noteSuffix}`,
+                        });
+                    }
+                }
+                else if (canBump(workflowRun, 1)) {
+                    runtime.status = "pending";
+                    appendTransition(workflowRun, spec.id, "awaiting_review", "pending", "tool", {
+                        code: "stage.retry.queued",
+                        message: `stage ${spec.id} rejected in review; queued for in-place retry (attempt ${runtime.attempts}/${retryLimitOf(spec)})`,
+                        detail: input.note,
+                    });
+                }
+            }
+            break;
+        }
+        case "retreat": {
+            requireRunning();
+            const target = requireStage(record, input.stageId);
+            const targetRuntime = runtimeOf(record, target.id);
+            if (targetRuntime === undefined)
+                throw new Error(`unknown stage: ${target.id}`);
+            const wasActivated = targetRuntime.status === "active" ||
+                targetRuntime.status === "awaiting_review" ||
+                targetRuntime.status === "completed" ||
+                targetRuntime.attempts > 0;
+            if (!wasActivated) {
+                throw new Error(`retreat target ${target.id} has never been activated; retreat targets a previously activated earlier stage`);
+            }
+            crossStageRetreat(workflowRun, target, "tool", input.note ?? "explicit retreat");
+            break;
+        }
+        case "complete": {
+            requireRunning();
+            const spec = requireStage(record, input.stageId);
+            const runtime = runtimeOf(record, spec.id);
+            if (runtime === undefined)
+                throw new Error(`unknown stage: ${spec.id}`);
+            if (spec.planId !== undefined) {
+                throw new Error(`stage ${spec.id} references plan ${spec.planId}; complete only applies to checkpoint stages without planId — plan-backed stages settle via plan completion and evaluation`);
+            }
+            if (runtime.status !== "active") {
+                throw new Error(`stage ${spec.id} is ${runtime.status}; complete requires an active checkpoint stage`);
+            }
+            const items = input.evidence ?? [];
+            if (items.length === 0)
+                throw new Error(`stage ${spec.id}: complete requires evidence`);
+            const covered = new Set();
+            for (const item of items) {
+                if (spec.objective.acceptance.length > 0) {
+                    if (item.acceptanceId === undefined ||
+                        !spec.objective.acceptance.some((entry) => entry.id === item.acceptanceId)) {
+                        throw new Error(`stage ${spec.id}: evidence acceptanceId must reference the declared acceptance items`);
+                    }
+                    covered.add(item.acceptanceId);
+                }
+            }
+            const missing = spec.objective.acceptance.filter((item) => !covered.has(item.id)).map((item) => item.id);
+            if (missing.length > 0) {
+                throw new Error(`stage ${spec.id}: evidence does not cover acceptance [${missing.join(", ")}]`);
+            }
+            if (!canBump(workflowRun, 1))
+                break;
+            runtime.evidence = [...runtime.evidence, ...normalizeEvidence(items)];
+            runtime.status = "completed";
+            appendTransition(workflowRun, spec.id, "active", "completed", "tool", {
+                code: spec.objective.acceptance.length > 0 ? "stage.completed.acceptance-covered" : "stage.completed",
+                message: `stage ${spec.id} completed at checkpoint`,
+                detail: items.map((item) => item.ref).join("; "),
+            });
+            break;
+        }
+        case "skip": {
+            const spec = requireStage(record, input.stageId);
+            const runtime = runtimeOf(record, spec.id);
+            if (runtime === undefined)
+                throw new Error(`unknown stage: ${spec.id}`);
+            if (runtime.status !== "pending") {
+                throw new Error(`stage ${spec.id} is ${runtime.status}; only pending stages can be skipped`);
+            }
+            if (!canBump(workflowRun, 1))
+                break;
+            // §5 rule 6: skipped counts as completed for dependency unlocking —
+            // an explicit scope ruling, applied uniformly in closure checks.
+            runtime.status = "skipped";
+            appendTransition(workflowRun, spec.id, "pending", "skipped", "tool", {
+                code: "stage.skipped",
+                message: `stage ${spec.id} skipped (explicit scope ruling)`,
+                detail: input.note,
+            });
+            break;
+        }
+        case "cancel": {
+            const from = record.status;
+            // §5 rule 6: every non-terminal stage becomes skipped; referenced
+            // active plans are left untouched (soft reference — the plan domain
+            // keeps its own sovereignty).
+            for (const spec of record.stages) {
+                const runtime = runtimeOf(record, spec.id);
+                if (runtime === undefined || runtime.status === "completed" || runtime.status === "skipped")
+                    continue;
+                if (!canBump(workflowRun, 1))
+                    break;
+                const stageFrom = runtime.status;
+                runtime.status = "skipped";
+                appendTransition(workflowRun, spec.id, stageFrom, "skipped", "tool", {
+                    code: "stage.skipped",
+                    message: `stage ${spec.id} skipped by workflow cancellation`,
+                });
+            }
+            if (!canBump(workflowRun, 1))
+                break;
+            record.status = "cancelled";
+            appendTransition(workflowRun, undefined, from, "cancelled", "tool", {
+                code: "workflow.cancelled",
+                message: `workflow cancelled (non-terminal stages skipped)`,
+                detail: input.note,
+            });
+            break;
+        }
+    }
+    if (record.status === "running")
+        reevaluateWorkflow(workflowRun, "tool");
+    run.transitions.push(...workflowRun.transitions);
+    if (workflowRun.hitLimit)
+        run.cascadeLimitReached = true;
+    return run;
+}
+// ---------------------------------------------------------------------------
+// Inspection (§8.1 waiting conditions + acceptance coverage)
+// ---------------------------------------------------------------------------
+/**
+ * The §8.1 waiting-condition label for one stage, or null when nothing is
+ * blocking it. Label ownership: `acceptance-missing` is exclusively the
+ * acceptance-mode retry wait (pending with attempts > 0); `retry-wait` is the
+ * lower-bound retry wait (pending with attempts > 0 and no acceptance
+ * declared — the plan completed but its evidence is empty); an active stage
+ * whose plan is not completed yet is `plan-incomplete`. The check order
+ * mirrors activationPass (§8.1: active-limit precedes write-scope conflict),
+ * so the inspect label always names the same condition the audit recorded.
+ */
+export function computeWaitingOn(workflow, spec, runtime, deps) {
+    if (runtime.status === "awaiting_review")
+        return "review";
+    if (runtime.status === "pending") {
+        if (workflow.status === "draft")
+            return "not-yet-active";
+        if (runtime.attempts > 0) {
+            if (spec.objective.acceptance.length === 0)
+                return "retry-wait"; // lower-bound retry wait
+            return `acceptance-missing:[${uncoveredAcceptanceIds(spec, runtime).join(", ")}]`;
+        }
+        const incomplete = spec.dependsOn.filter((dep) => {
+            const dependency = runtimeOf(workflow, dep);
+            return !(dependency !== undefined && (dependency.status === "completed" || dependency.status === "skipped"));
+        });
+        if (incomplete.length > 0)
+            return `deps-incomplete:[${incomplete.join(", ")}]`;
+        if (spec.planId !== undefined && deps.getPlan(spec.planId) === undefined)
+            return "plan-dangling";
+        if (activeCount(workflow) >= maxActiveOf(workflow))
+            return "active-limit";
+        if (spec.kind === "write") {
+            const conflict = findWriteConflict(workflow, spec);
+            if (conflict !== undefined)
+                return `write-scope-conflict:[${conflict.id}]`;
+        }
+        return "not-yet-active";
+    }
+    if (runtime.status === "active") {
+        if (spec.planId === undefined)
+            return null; // checkpoint waiting for the explicit complete action
+        const plan = deps.getPlan(spec.planId);
+        if (plan === undefined)
+            return "plan-dangling";
+        if (plan.status !== "completed")
+            return "plan-incomplete";
+        return null; // completed plan, evaluation pending the next reevaluation trigger
+    }
+    return null;
+}
+/** §5 rule 6 inspect payload: full snapshot plus per-stage waiting conditions and acceptance coverage (§8.1). */
+export function inspectWorkflow(workflow, deps) {
+    return {
+        workflowId: workflow.id,
+        status: workflow.status,
+        stages: workflow.stages.map((spec) => {
+            const runtime = runtimeOf(workflow, spec.id);
+            const safeRuntime = runtime ?? {
+                stageId: spec.id,
+                status: "pending",
+                attempts: 0,
+                evidence: [],
+            };
+            const plan = spec.planId !== undefined ? deps.getPlan(spec.planId) : undefined;
+            return {
+                stageId: spec.id,
+                status: safeRuntime.status,
+                attempts: safeRuntime.attempts,
+                waitingOn: computeWaitingOn(workflow, spec, safeRuntime, deps),
+                ...(spec.planId !== undefined ? { planId: spec.planId, planStatus: plan?.status ?? "missing" } : {}),
+                acceptance: spec.objective.acceptance.map((item) => {
+                    const refs = safeRuntime.evidence
+                        .filter((entry) => entry.acceptanceId === item.id)
+                        .map((entry) => entry.ref);
+                    return { id: item.id, statement: item.statement, covered: refs.length > 0, refs };
+                }),
+            };
+        }),
+    };
+}
+//# sourceMappingURL=engine.js.map