@arronqzy/blueprint-dsl 0.0.1

package/src/runtime/blueprint-cycle.ts

@@ -0,0 +1,136 @@
+import { BLUEPRINT_NODE_TYPE } from "../nodes/definitions.js";
+import type { LibraryBlueprintResolver, RunnableGraph } from "./graph-runner.js";
+
+export const BLUEPRINT_CALL_STACK_KEY = "__blueprintCallStack";
+
+export class BlueprintCycleError extends Error {
+  readonly cycleIds: string[];
+
+  constructor(cycleIds: string[], message: string) {
+    super(message);
+    this.name = "BlueprintCycleError";
+    this.cycleIds = cycleIds;
+  }
+}
+
+export function collectBlueprintLibraryRefs(graph: RunnableGraph): string[] {
+  const ids = new Set<string>();
+  for (const node of graph.nodes) {
+    if (node.nodeType === BLUEPRINT_NODE_TYPE && node.libraryBlueprintId) {
+      ids.add(node.libraryBlueprintId);
+    }
+  }
+  return [...ids];
+}
+
+export function formatBlueprintCycleMessage(
+  cycleIds: string[],
+  resolveName?: (libraryBlueprintId: string) => string
+): string {
+  const labels = cycleIds.map((id) => resolveName?.(id) ?? id);
+  return `蓝图引用存在死循环：${labels.join(" → ")}`;
+}
+
+export type BlueprintCycleCheckOptions = {
+  rootGraph: RunnableGraph;
+  /** 当前蓝图对应的蓝图库 id；工作区蓝图未入库时为 null */
+  rootLibraryBlueprintId?: string | null;
+  resolveLibraryBlueprint: LibraryBlueprintResolver;
+  resolveBlueprintName?: (libraryBlueprintId: string) => string;
+};
+
+export type BlueprintCycleCheckResult =
+  | { ok: true }
+  | { ok: false; cycleIds: string[]; message: string };
+
+export async function detectBlueprintReferenceCycle(
+  options: BlueprintCycleCheckOptions
+): Promise<BlueprintCycleCheckResult> {
+  const {
+    rootGraph,
+    rootLibraryBlueprintId,
+    resolveLibraryBlueprint,
+    resolveBlueprintName,
+  } = options;
+
+  const graphCache = new Map<string, RunnableGraph | null>();
+
+  const loadGraph = async (libraryBlueprintId: string) => {
+    if (!graphCache.has(libraryBlueprintId)) {
+      graphCache.set(
+        libraryBlueprintId,
+        await resolveLibraryBlueprint(libraryBlueprintId)
+      );
+    }
+    return graphCache.get(libraryBlueprintId) ?? null;
+  };
+
+  const visit = async (
+    path: string[],
+    graph: RunnableGraph
+  ): Promise<string[] | null> => {
+    for (const refId of collectBlueprintLibraryRefs(graph)) {
+      const cycleIndex = path.indexOf(refId);
+      if (cycleIndex !== -1) {
+        return [...path.slice(cycleIndex), refId];
+      }
+
+      const nested = await loadGraph(refId);
+      if (!nested) continue;
+
+      const cycle = await visit([...path, refId], nested);
+      if (cycle) return cycle;
+    }
+    return null;
+  };
+
+  const initialPath = rootLibraryBlueprintId ? [rootLibraryBlueprintId] : [];
+  const cycleIds = await visit(initialPath, rootGraph);
+
+  if (!cycleIds) {
+    return { ok: true };
+  }
+
+  return {
+    ok: false,
+    cycleIds,
+    message: formatBlueprintCycleMessage(cycleIds, resolveBlueprintName),
+  };
+}
+
+export async function assertNoBlueprintReferenceCycle(
+  options: BlueprintCycleCheckOptions
+): Promise<void> {
+  const result = await detectBlueprintReferenceCycle(options);
+  if (!result.ok) {
+    throw new BlueprintCycleError(result.cycleIds, result.message);
+  }
+}
+
+export function resolveBlueprintCallStack(
+  scopeStack: string[] | undefined,
+  rootLibraryBlueprintId?: string | null
+): string[] {
+  if (scopeStack) return scopeStack;
+  return rootLibraryBlueprintId ? [rootLibraryBlueprintId] : [];
+}
+
+export function detectRuntimeBlueprintCycle(
+  callStack: string[],
+  targetLibraryBlueprintId: string,
+  resolveName?: (libraryBlueprintId: string) => string
+): BlueprintCycleCheckResult {
+  const cycleIndex = callStack.indexOf(targetLibraryBlueprintId);
+  if (cycleIndex === -1) {
+    return { ok: true };
+  }
+  const cycleIds = [
+    ...callStack.slice(cycleIndex),
+    targetLibraryBlueprintId,
+  ];
+  return {
+    ok: false,
+    cycleIds,
+    message: formatBlueprintCycleMessage(cycleIds, resolveName),
+  };
+}

package/src/runtime/clock-active-registry.ts

@@ -0,0 +1,30 @@
+const activeClockNodeIds = new Set<string>();
+const listeners = new Set<() => void>();
+
+function emit() {
+  listeners.forEach((listener) => listener());
+}
+
+export function markClockNodeActive(nodeId: string) {
+  if (activeClockNodeIds.has(nodeId)) return;
+  activeClockNodeIds.add(nodeId);
+  emit();
+}
+
+export function markClockNodeInactive(nodeId: string) {
+  if (!activeClockNodeIds.delete(nodeId)) return;
+  emit();
+}
+
+export function isClockNodeActive(nodeId: string): boolean {
+  return activeClockNodeIds.has(nodeId);
+}
+
+export function getActiveClockNodeIds(): string[] {
+  return [...activeClockNodeIds];
+}
+
+export function subscribeActiveClockNodes(listener: () => void) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}

package/src/runtime/clock-scheduler.ts

@@ -0,0 +1,49 @@
+import {
+  buildClockSignalValue,
+  normalizeClockConfig,
+  startClockSchedule,
+  stopAllClockSchedules,
+  stopClockSchedule,
+  abortClockSession,
+  isClockScheduleActive,
+  isClockSessionAborted,
+  clearClockSessionAbort,
+  validateClockScheduleConfig,
+  type ClockNodeConfig,
+} from "../clock-config.js";
+import {
+  markClockNodeActive,
+  markClockNodeInactive,
+} from "./clock-active-registry.js";
+
+export function buildClockSessionKey(scopeId: string, nodeId: string): string {
+  return `${scopeId}:${nodeId}`;
+}
+
+export function abortClockNode(scopeId: string, nodeId: string): void {
+  abortClockSession(buildClockSessionKey(scopeId, nodeId));
+  markClockNodeInactive(nodeId);
+}
+
+export function scheduleClockOutputs(options: {
+  sessionKey: string;
+  config: ClockNodeConfig;
+  onTick: () => void | Promise<void>;
+  onSettled?: () => void;
+}): () => void {
+  return startClockSchedule(options);
+}
+
+export {
+  stopClockSchedule,
+  stopAllClockSchedules,
+  abortClockSession,
+  isClockScheduleActive,
+  isClockSessionAborted,
+  clearClockSessionAbort,
+  validateClockScheduleConfig,
+};
+
+export function createClockOutputValue(config: ClockNodeConfig) {
+  return buildClockSignalValue(normalizeClockConfig(config));
+}

package/src/runtime/execution-trace.ts

@@ -0,0 +1,55 @@
+import type { Value } from "../type.js";
+import { isFalseSignal, isTrueSignal } from "../node-signal.js";
+
+export type ExecutionTraceEntry = {
+  id: string;
+  nodeId: string;
+  nodeLabel?: string;
+  nodeType: string;
+  startedAt: number;
+  finishedAt: number;
+  isoTime: string;
+  inputs: Record<string, unknown>;
+  outputs: Record<string, unknown>;
+  error?: string;
+  /** 时钟节点第几次 tick（从 1 开始） */
+  clockTickIndex?: number;
+  /** 时钟节点本次调度总 tick 数 */
+  clockTickTotal?: number;
+};
+
+export type ExecutionRunRecord = {
+  runId: string;
+  blueprintId: string | null;
+  blueprintName: string;
+  lifecycleNodeId: string;
+  lifecycleNodeLabel?: string;
+  lifecyclePhase?: string;
+  startedAt: number;
+  finishedAt?: number;
+  status: "running" | "completed" | "paused" | "failed";
+  entries: ExecutionTraceEntry[];
+};
+
+export function serializeTraceValue(value: Value | undefined): unknown {
+  if (value === undefined) return undefined;
+  if (isTrueSignal(value)) {
+    return {
+      kind: "true",
+      value: value.value,
+      isoTime: value.isoTime,
+    };
+  }
+  if (isFalseSignal(value)) {
+    return {
+      kind: "false",
+      error: value.error,
+      isoTime: value.isoTime,
+    };
+  }
+  return value;
+}
+
+export function createTraceEntryId() {
+  return `trace_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+}