qlogicagent 2.13.5 → 2.13.6

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

@@ -1,522 +0,0 @@
-/**
- * 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

@@ -1,116 +0,0 @@
-/**
- * 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[];