qlogicagent 2.13.4 → 2.13.5

package/dist/orchestration/workflow/workflow-controller.js

@@ -0,0 +1,522 @@
+/**
+ * Workflow Controller — automation driver: create / run / pause / resume + concurrency (spec §B4/B5).
+ *
+ * Owns workflow lifecycle on top of the WorkflowStore (persistence) and WorkflowRuntime (execution).
+ * Concurrency (spec §B5): when a workflow is triggered while a previous run is still in-flight, the
+ * record's `concurrency` policy decides:
+ *   - "skip"     -> drop the new trigger (returns status "skipped")
+ *   - "queue"    -> run after the current one finishes. Each trigger gets a fresh runtime/cache;
+ *                   only pause/resume of the SAME run reuses runtime state.
+ *   - "parallel" -> start a fresh independent runtime concurrently (own cache)
+ *
+ * The caller supplies a `runtimeFactory` so host capabilities (D13), the node registry, the
+ * budget/permission gate (D15), and the clock are injected per workflow — the controller never
+ * imports those subsystems (engine stays a pure executor; plan D12).
+ *
+ * fail-loud: unknown workflow ids throw; executor/gate errors propagate out of run().
+ */
+import { WorkflowRunCanceled } from "./workflow-runtime.js";
+import { WorkflowRuntime as WorkflowRuntimeImpl } from "./workflow-runtime.js";
+import { BudgetPermissionGate, } from "./budget-permission-gate.js";
+import { applyPatch, PatchError, validateWorkflowDef, } from "./workflow-patch.js";
+import { renderWorkflow } from "./workflow-render.js";
+import { convertN8nWorkflow } from "./n8n-import.js";
+import { buildNodeRecords, } from "./run-history-store.js";
+import { randomUUID } from "node:crypto";
+export class WorkflowController {
+    store;
+    runtimeFactory;
+    runHistory;
+    slots = new Map();
+    activeRuns = new Map();
+    activeRunIdsByWorkflow = new Map();
+    suppressedHistoryRunIds = new Set();
+    constructor(store, runtimeFactory, 
+    /** Optional durable run-history recorder. Wired here (not the handler) so every
+     *  trigger path — manual RPC, cron scheduler, IM, webhook — is captured alike. */
+    runHistory) {
+        this.store = store;
+        this.runtimeFactory = runtimeFactory;
+        this.runHistory = runHistory;
+    }
+    // ── CRUD (single store, last-write-wins; D17) ────────────
+    async create(input) {
+        const defErrors = validateWorkflowDef(input.def);
+        if (defErrors.length > 0)
+            throw new PatchError(defErrors);
+        const now = new Date().toISOString();
+        const record = {
+            id: input.id,
+            name: input.name,
+            ...(input.owner ? { owner: input.owner } : {}),
+            def: input.def,
+            active: input.active ?? false,
+            concurrency: input.concurrency ?? "queue",
+            rev: 1,
+            createdAt: now,
+            updatedAt: now,
+        };
+        await this.store.save(record);
+        return record;
+    }
+    async update(id, patch) {
+        const rec = await this.store.require(id);
+        const next = { ...rec, ...patch, updatedAt: new Date().toISOString() };
+        if (patch.def !== undefined) {
+            const defErrors = validateWorkflowDef(next.def);
+            if (defErrors.length > 0)
+                throw new PatchError(defErrors);
+        }
+        await this.store.save(next);
+        return next;
+    }
+    async setActive(id, active) {
+        if (active) {
+            const rec = await this.store.require(id);
+            // D31: triggers run the PUBLISHED snapshot — an unpublished draft has nothing safe to run.
+            if (!rec.publishedDef)
+                throw new Error(`Workflow "${id}" has no published version — publish the draft before activating`);
+            if (rec.archived)
+                throw new Error(`Workflow "${id}" is archived — restore it before activating`);
+        }
+        return this.update(id, { active });
+    }
+    /**
+     * Publish (D31): snapshot the current draft (`def`) as the version triggers execute.
+     * Editing the draft afterwards never touches the running version until the next publish.
+     */
+    async publish(id) {
+        const rec = await this.store.require(id);
+        if (rec.archived)
+            throw new Error(`Workflow "${id}" is archived — restore it before publishing`);
+        const defErrors = validateWorkflowDef(rec.def);
+        if (defErrors.length > 0)
+            throw new PatchError(defErrors);
+        const next = {
+            ...rec,
+            publishedDef: structuredClone(rec.def),
+            publishedRev: rec.rev,
+            updatedAt: new Date().toISOString(),
+        };
+        await this.store.save(next);
+        return next;
+    }
+    /** Archive (D31): keep the data, kill the lifecycle (deactivates; activation/publish refuse). */
+    async archive(id, archived) {
+        const rec = await this.store.require(id);
+        const next = {
+            ...rec,
+            archived,
+            ...(archived ? { active: false } : {}),
+            updatedAt: new Date().toISOString(),
+        };
+        await this.store.save(next);
+        return next;
+    }
+    /**
+     * Revert a workflow to a stored revision snapshot (undo 基座). Git-revert semantics:
+     * the snapshot's def/name/trigger are re-applied as a NEW revision (rev bumps), so
+     * history stays forward-only and optimistic-concurrency baseRev checks keep working.
+     * fail-loud: unknown id or pruned/absent revision throws.
+     */
+    async revertTo(id, rev) {
+        const rec = await this.store.require(id);
+        const snap = await this.store.loadRevision(id, rev);
+        if (!snap)
+            throw new Error(`Workflow "${id}" has no stored revision ${rev}`);
+        const defErrors = validateWorkflowDef(snap.def);
+        if (defErrors.length > 0)
+            throw new PatchError(defErrors);
+        const next = {
+            ...rec,
+            def: snap.def,
+            name: snap.name,
+            trigger: snap.trigger ?? null,
+            rev: rec.rev + 1,
+            updatedAt: new Date().toISOString(),
+        };
+        await this.store.save(next);
+        return next;
+    }
+    /**
+     * Import an n8n workflow JSON (read-format only, plan M5 §2.1) into the single store. Converts
+     * via the deterministic translator then routes through `create`, so the graph passes the same
+     * `validateWorkflowDef` gate every write path uses — fail-loud on unsupported nodes or bad graph.
+     */
+    async importN8n(id, json, opts = {}) {
+        const { name, def, report } = convertN8nWorkflow(json, id);
+        const record = await this.create({ id, name, def, concurrency: opts.concurrency, owner: opts.owner });
+        return { record, report };
+    }
+    /** Load a single record or throw (fail-loud lookup; used by the scheduler to re-read triggers). */
+    async get(id) {
+        return this.store.require(id);
+    }
+    /**
+     * Render a workflow as compact agent-context text (spec §B / §A `get`). Fail-loud on unknown id.
+     * This is the engine half of the agent `workflow.get`/describe action: the agent reads this and
+     * emits a WorkflowPatch against the shown `rev`.
+     */
+    async describe(id, opts) {
+        const rec = await this.store.require(id);
+        return renderWorkflow(rec, opts);
+    }
+    /**
+     * Apply a WorkflowPatch — the single mutation channel for agent edits and canvas hand-edits
+     * (spec §C). Loads the latest record, applies the patch transactionally through the engine
+     * (scope enforcement + validateDag), bumps `rev`, and persists. Optimistic concurrency (LWW):
+     *   - baseRev omitted or == current rev → apply against the latest.
+     *   - baseRev < current rev (someone edited in between) → replay onto the latest; if every op
+     *     still references valid nodes/edges it applies (last-write-wins), otherwise a conflict is
+     *     returned so the caller can redo against the latest rendering.
+     * A rejected patch (illegal op / scope violation / invalid graph) throws PatchError unchanged.
+     */
+    async patch(id, env) {
+        const rec = await this.store.require(id);
+        const stale = env.baseRev !== undefined && env.baseRev < rec.rev;
+        const target = {
+            def: rec.def,
+            meta: { name: rec.name, active: rec.active, trigger: rec.trigger ?? null },
+        };
+        let applied;
+        let next;
+        try {
+            const res = applyPatch(target, env);
+            applied = res.applied;
+            next = res.target;
+        }
+        catch (err) {
+            // A stale base whose ops no longer fit the latest graph is a real LWW conflict, not a
+            // caller bug — surface it so the agent/canvas can redo against the latest.
+            if (stale && err instanceof PatchError) {
+                return { ok: false, conflict: { latestRev: rec.rev } };
+            }
+            throw err;
+        }
+        // D31 single-track activation guard: set_meta{active:true} must obey the same publish
+        // requirement as setActive — a patch is not a side door around the lifecycle.
+        const turningActive = next.meta.active === true && !rec.active;
+        if (turningActive && !rec.publishedDef) {
+            throw new PatchError([`workflow "${id}" has no published version — publish the draft before activating (set_meta.active)`]);
+        }
+        const updated = {
+            ...rec,
+            def: next.def,
+            name: next.meta.name ?? rec.name,
+            active: next.meta.active ?? rec.active,
+            trigger: next.meta.trigger ?? null,
+            rev: rec.rev + 1,
+            updatedAt: new Date().toISOString(),
+        };
+        await this.store.save(updated);
+        return { ok: true, rev: updated.rev, applied };
+    }
+    // ── Execution lifecycle ──────────────────────────────────
+    /** Trigger a run, honoring the workflow's concurrency policy (spec §B5). */
+    async run(id, trigger, opts = {}) {
+        const rec = await this.store.require(id);
+        if (rec.archived)
+            throw new Error(`Workflow "${id}" is archived and cannot run`);
+        const triggerType = trigger?.type ?? "manual";
+        // D31 version selection: attended runs (manual/intent/form — a person just asked) execute
+        // the DRAFT (edit-test loop); unattended triggers execute the PUBLISHED snapshot only — an
+        // in-progress edit must never change what cron/webhook/IM fires.
+        const attended = triggerType === "manual" || triggerType === "intent" || triggerType === "form";
+        let runDef;
+        if (attended) {
+            runDef = rec.def;
+        }
+        else {
+            if (!rec.publishedDef)
+                throw new Error(`Workflow "${id}" has no published version — unattended trigger "${triggerType}" refused`);
+            runDef = rec.publishedDef;
+        }
+        const ctx = {
+            workflowId: id,
+            runId: randomUUID(),
+            type: triggerType,
+            payload: trigger?.payload,
+            permissionScope: rec.permissionScope,
+            reuseCache: opts.reuseCache === true,
+        };
+        const slot = this.slotFor(id);
+        const start = () => {
+            if (slot.pending > 0) {
+                switch (rec.concurrency) {
+                    case "skip":
+                        return Promise.resolve({ workflowId: id, status: "skipped" });
+                    case "parallel":
+                        return this.startParallel(id, runDef, ctx);
+                    case "queue":
+                        return this.track(id, slot, runDef, ctx, true);
+                }
+            }
+            return this.track(id, slot, runDef, ctx, false);
+        };
+        return this.recordRun(id, ctx, start, opts.recordHistory === false);
+    }
+    /**
+     * Wrap a run with durable history recording (when wired). Lives at this choke point —
+     * not in the RPC handler — so cron/IM/webhook runs are recorded identically to manual
+     * ones. History writes are best-effort: a recording failure never blocks the run.
+     */
+    async recordRun(id, ctx, start, skipHistory = false) {
+        const startedAtMs = Date.now();
+        if (!this.runHistory || skipHistory) {
+            try {
+                const outcome = await start();
+                return { ...outcome, runId: outcome.runId ?? ctx.runId };
+            }
+            catch (err) {
+                if (err instanceof WorkflowRunCanceled) {
+                    return { workflowId: id, status: "canceled", runId: ctx.runId };
+                }
+                throw err;
+            }
+        }
+        await this.runHistory
+            .begin(id, { runId: ctx.runId, triggerType: ctx.type, startedAt: new Date(startedAtMs).toISOString() })
+            .catch(() => undefined);
+        const finish = (patch) => this.finishRunHistory(id, ctx.runId, startedAtMs, patch);
+        try {
+            const outcome = await start();
+            await finish({
+                status: outcome.status,
+                ...(outcome.result ? { nodes: buildNodeRecords(outcome.result) } : {}),
+            });
+            return { ...outcome, runId: ctx.runId };
+        }
+        catch (err) {
+            if (err instanceof WorkflowRunCanceled) {
+                await finish({ status: "canceled", error: err.message });
+                return { workflowId: id, status: "canceled", runId: ctx.runId };
+            }
+            await finish({ status: "failed", error: err instanceof Error ? err.message : String(err) });
+            throw err;
+        }
+    }
+    /** Cooperatively pause the in-flight run; it suspends before the next node (cache retained). */
+    pause(id, opts = {}) {
+        const active = this.requireActiveRun(id, opts.runId);
+        active.runtime.pause();
+    }
+    /** Resume a paused workflow: re-run the same runtime so cached nodes hit and only the
+     * unfinished remainder executes. When the run paused on an exhausted budget, pass `extraBudget`
+     * to raise the gate's ceiling first (D15 "抬预算后 resume"); otherwise the first not-yet-run
+     * node would immediately re-trip the same budget and pause again. */
+    async resume(id, opts = {}) {
+        const active = this.requireActiveRun(id, opts.runId);
+        if (active.status !== "paused") {
+            throw new Error(`Workflow "${id}" run "${active.runId}" is not paused`);
+        }
+        if (opts.extraBudget)
+            active.runtime.extendBudget(opts.extraBudget);
+        active.status = "running";
+        const slot = this.slotFor(id);
+        slot.pending++;
+        const settled = active.runtime
+            .run()
+            .then(async (result) => {
+            const outcome = { workflowId: id, runId: active.runId, status: result.status, result };
+            if (result.status === "paused") {
+                active.status = "paused";
+            }
+            else {
+                this.unregisterActiveRun(active.runId);
+            }
+            await this.finishRunHistory(id, active.runId, active.startedAtMs, {
+                status: outcome.status,
+                nodes: buildNodeRecords(result),
+            });
+            return outcome;
+        })
+            .catch(async (err) => {
+            this.unregisterActiveRun(active.runId);
+            if (err instanceof WorkflowRunCanceled) {
+                await this.finishRunHistory(id, active.runId, active.startedAtMs, {
+                    status: "canceled",
+                    error: err.message,
+                });
+                return { workflowId: id, runId: active.runId, status: "canceled" };
+            }
+            await this.finishRunHistory(id, active.runId, active.startedAtMs, {
+                status: "failed",
+                error: err instanceof Error ? err.message : String(err),
+            });
+            throw err;
+        })
+            .finally(() => { slot.pending--; });
+        slot.tail = settled.catch(() => undefined);
+        return settled;
+    }
+    async cancelRun(id, opts = {}) {
+        const active = this.requireActiveRun(id, opts.runId);
+        const reason = opts.reason ?? `Workflow "${id}" run "${active.runId}" canceled`;
+        const err = new WorkflowRunCanceled(reason);
+        active.runtime.cancel(reason);
+        if (!active.abortController.signal.aborted)
+            active.abortController.abort(err);
+        this.unregisterActiveRun(active.runId);
+        if (active.status === "paused") {
+            await this.finishRunHistory(id, active.runId, active.startedAtMs, {
+                status: "canceled",
+                error: reason,
+            });
+        }
+        return { workflowId: id, runId: active.runId, status: "canceled" };
+    }
+    async delete(id) {
+        const activeRunIds = [...(this.activeRunIdsByWorkflow.get(id) ?? [])];
+        for (const runId of activeRunIds) {
+            this.suppressedHistoryRunIds.add(runId);
+            await this.cancelRun(id, { runId, reason: `Workflow "${id}" deleted` }).catch(() => undefined);
+        }
+        this.slots.delete(id);
+        await this.store.delete(id);
+    }
+    /** Active workflows whose triggers the gateway should re-register after restart (spec §B4). */
+    async listActive() {
+        return this.store.listActive();
+    }
+    // ── internals ────────────────────────────────────────────
+    slotFor(id) {
+        let slot = this.slots.get(id);
+        if (!slot) {
+            slot = { tail: Promise.resolve(), pending: 0 };
+            this.slots.set(id, slot);
+        }
+        return slot;
+    }
+    registerActiveRun(active) {
+        this.activeRuns.set(active.runId, active);
+        let ids = this.activeRunIdsByWorkflow.get(active.workflowId);
+        if (!ids) {
+            ids = new Set();
+            this.activeRunIdsByWorkflow.set(active.workflowId, ids);
+        }
+        ids.add(active.runId);
+    }
+    unregisterActiveRun(runId) {
+        const active = this.activeRuns.get(runId);
+        if (!active)
+            return;
+        this.activeRuns.delete(runId);
+        const ids = this.activeRunIdsByWorkflow.get(active.workflowId);
+        if (!ids)
+            return;
+        ids.delete(runId);
+        if (ids.size === 0)
+            this.activeRunIdsByWorkflow.delete(active.workflowId);
+    }
+    requireActiveRun(workflowId, runId) {
+        if (runId) {
+            const active = this.activeRuns.get(runId);
+            if (!active || active.workflowId !== workflowId) {
+                throw new Error(`Workflow "${workflowId}" has no active run "${runId}"`);
+            }
+            return active;
+        }
+        const ids = [...(this.activeRunIdsByWorkflow.get(workflowId) ?? [])];
+        const latestRunId = this.slots.get(workflowId)?.latestRunId;
+        if (latestRunId && ids.includes(latestRunId))
+            return this.activeRuns.get(latestRunId);
+        const fallback = ids.at(-1);
+        if (!fallback)
+            throw new Error(`Workflow "${workflowId}" has no active run`);
+        return this.activeRuns.get(fallback);
+    }
+    async finishRunHistory(workflowId, runId, startedAtMs, patch) {
+        if (!this.runHistory || this.suppressedHistoryRunIds.has(runId))
+            return;
+        await this.runHistory
+            .finish(workflowId, runId, {
+            finishedAt: new Date().toISOString(),
+            durationMs: Date.now() - startedAtMs,
+            ...patch,
+        })
+            .catch(() => undefined);
+    }
+    /**
+     * Track a fresh or queued run on the slot. `chained` runs wait for the slot's tail (the prior
+     * run) before starting → strict serialization for the "queue" policy. `pending` is incremented
+     * synchronously so concurrent triggers observe the slot as busy across the run→queue handoff.
+     */
+    track(id, slot, def, ctx, chained) {
+        slot.pending++;
+        const begin = () => this.startTrackedRuntime(id, slot, def, ctx);
+        const started = chained ? slot.tail.then(begin) : begin();
+        const settled = started.finally(() => { slot.pending--; });
+        slot.tail = settled.catch(() => undefined);
+        return settled;
+    }
+    async startParallel(id, def, ctx) {
+        return this.startTrackedRuntime(id, undefined, def, ctx);
+    }
+    async startTrackedRuntime(id, slot, def, ctx) {
+        const abortController = new AbortController();
+        const runtime = this.runtimeFactory(def, { ...ctx, signal: abortController.signal });
+        const active = {
+            workflowId: id,
+            runId: ctx.runId,
+            startedAtMs: Date.now(),
+            runtime,
+            abortController,
+            status: "running",
+        };
+        this.registerActiveRun(active);
+        if (slot) {
+            slot.runtime = runtime;
+            slot.latestRunId = ctx.runId;
+        }
+        try {
+            const result = await runtime.run();
+            const outcome = { workflowId: id, runId: ctx.runId, status: result.status, result };
+            if (result.status === "paused") {
+                active.status = "paused";
+            }
+            else {
+                this.unregisterActiveRun(ctx.runId);
+            }
+            return outcome;
+        }
+        catch (err) {
+            this.unregisterActiveRun(ctx.runId);
+            throw err;
+        }
+    }
+}
+/**
+ * The production RuntimeFactory: builds a WorkflowRuntime wired with the D15 BudgetPermissionGate
+ * derived from the run's trigger kind. This is the consumer that turns the gate from a bare
+ * interface into an enforced guarantee — every run the controller starts through this factory has
+ * its per-run budget and (for unattended triggers) its permission allowlist checked before each
+ * node. Hosts supply the registry/host capabilities and the budget ceilings; the gate wiring is
+ * fixed so no run can accidentally execute ungated.
+ */
+export function defaultRuntimeFactory(opts) {
+    return (def, ctx) => new WorkflowRuntimeImpl(def, {
+        registry: opts.registry,
+        host: opts.host,
+        signal: ctx.signal,
+        // R5 reuseCache:工作流级共享 checkpoint("shared-cache" 槽)替代 per-run 槽 ——
+        // 起跑 seed 上次产物签名,完成后保留 → 改参数只重跑下游。内容寻址保证语义安全
+        // (kind+params+inputs 任一变化即 miss)。
+        checkpoint: opts.checkpoint?.(ctx.workflowId, ctx.reuseCache ? "shared-cache" : ctx.runId),
+        preserveCheckpoint: ctx.reuseCache === true,
+        trigger: ctx.payload,
+        triggerKind: ctx.type,
+        now: opts.now,
+        onNodeStatus: opts.emitNodeStatus
+            ? (nodeId, status) => opts.emitNodeStatus(ctx.workflowId, nodeId, status)
+            : undefined,
+        gate: new BudgetPermissionGate({
+            trigger: ctx.type,
+            maxNodeExecutions: opts.budget.maxNodeExecutions,
+            maxDurationMs: opts.budget.maxDurationMs,
+            // D30: the record's owner-granted unattended allowlist takes precedence over any
+            // host-level static default — the grant is per-workflow, not per-process.
+            allowUnattendedKinds: ctx.permissionScope?.allowUnattendedKinds ?? opts.allowUnattendedKinds,
+            now: opts.now ? () => opts.now().getTime() : undefined,
+        }),
+    });
+}

package/dist/orchestration/workflow/workflow-patch.d.ts

@@ -0,0 +1,116 @@
+/**
+ * WorkflowPatch — the single mutation channel for workflow editing (plan D17/D19,
+ * spec workflow-conversational-editing-spec.md §C).
+ *
+ * One change protocol for BOTH agent edits and canvas hand-edits: every edit is a list of
+ * `WorkflowPatch` ops applied transactionally to a workflow's graph. This module is the
+ * deterministic ENGINE half (no gateway, no UI, no LLM):
+ *   - applies the 8 ops to a WorkflowDef (+ workflow meta/trigger),
+ *   - enforces scoped-edit boundaries (框选批注: ops may only touch the selection subgraph,
+ *     D19) at the PROTOCOL level — not a prompt soft-constraint,
+ *   - validates the resulting graph through DagScheduler v2's invariants (acyclic minus
+ *     loopBack, edge integrity, loop maxIterations) — the spec's "patch 落库前过 validateDag".
+ *
+ * Transactional + fail-loud (§1.5): a patch is all-or-nothing. The candidate is built on a deep
+ * clone; if any op is illegal, references a missing node/edge, breaks scope, or yields an invalid
+ * graph, the WHOLE patch is rejected via `PatchError` (carrying `errors` for agent self-correction)
+ * and the input is never mutated. No partial application, no silent drop.
+ */
+import type { WorkflowDef, WorkflowNodeDef, DataEdge } from "./node-schema.js";
+import type { TriggerDef } from "./workflow-trigger.js";
+export type { TriggerDef } from "./workflow-trigger.js";
+/** A workflow trigger (spec §B / plan D7). Registered by the gateway trigger layer. */
+/** Workflow-global fields a patch can set (kept separate from the node graph). */
+export interface WorkflowMeta {
+    name?: string;
+    active?: boolean;
+    trigger?: TriggerDef | null;
+}
+/** The full mutable target of a patch: the node graph plus workflow-global meta. */
+export interface PatchTarget {
+    def: WorkflowDef;
+    meta: WorkflowMeta;
+}
+export type WorkflowPatch = {
+    op: "add_node";
+    node: WorkflowNodeDef;
+} | {
+    op: "remove_node";
+    nodeId: string;
+} | {
+    op: "update_params";
+    nodeId: string;
+    params: Record<string, unknown>;
+} | {
+    op: "rename_node";
+    nodeId: string;
+    name: string;
+} | {
+    op: "add_edge";
+    edge: DataEdge;
+} | {
+    op: "remove_edge";
+    edge: {
+        from: string;
+        to: string;
+        fromPort?: string;
+    };
+} | {
+    op: "set_trigger";
+    trigger: TriggerDef | null;
+} | {
+    op: "set_meta";
+    meta: {
+        name?: string;
+        active?: boolean;
+    };
+} | {
+    op: "set_node_options";
+    nodeId: string;
+    retry?: {
+        maxTries: number;
+        backoffMs?: number;
+    } | null;
+    timeoutMs?: number | null;
+    onError?: "stop" | "continue" | "errorPort" | null;
+} | {
+    op: "set_node_ui";
+    positions: Record<string, {
+        x: number;
+        y: number;
+    } | null>;
+};
+/** A patch + concurrency/scope envelope (spec §C). `scope` present ⇒ scoped (框选) edit. */
+export interface PatchEnvelope {
+    patch: WorkflowPatch[];
+    /** Optimistic-concurrency base revision (LWW handled by the store layer). */
+    baseRev?: number;
+    /** Selected node ids for a scoped edit; given ⇒ ops may only touch the selection subgraph. */
+    scope?: string[];
+}
+export interface ApplyResult {
+    target: PatchTarget;
+    applied: WorkflowPatch[];
+}
+/** Thrown when a patch is rejected. `errors` is the ordered list of reasons (for self-correction). */
+export declare class PatchError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/**
+ * Apply a patch transactionally. Returns a NEW PatchTarget (input untouched) or throws PatchError.
+ * Scope enforcement (when `scope` is set, spec §C):
+ *   - update_params / rename_node / remove_node: the node MUST be in scope.
+ *   - add_node: allowed; the new node joins the in-scope set for subsequent ops in this patch.
+ *   - add_edge / remove_edge: at least ONE endpoint must be in scope (selection-boundary edges).
+ *   - set_trigger / set_meta: workflow-global ⇒ rejected under a scoped edit.
+ */
+export declare function applyPatch(target: PatchTarget, env: PatchEnvelope): ApplyResult;
+/**
+ * Validate a standalone WorkflowDef against DagScheduler v2's invariants (acyclic minus loopBack,
+ * edge integrity, duplicate ids, loop maxIterations + hard cap). Returns a list of human-readable
+ * errors; empty ⇒ valid. This is the SAME graph gate `applyPatch` runs, exported so every
+ * persistence path (controller create/update) enforces identical invariants — single-track, no
+ * write path may bypass validation (D17 "一个 store").
+ */
+export declare function validateWorkflowDef(def: WorkflowDef): string[];