octoflow-core 1.0.0

package/dist/runtime/orchestration/pack.d.ts

@@ -0,0 +1,20 @@
+export { buildAgentTree, forkSession, spawnAgent, } from './pack/coordination.js';
+export type { CoordinationEvent, CoordinationEventKind, ForkInheritOptions, ForkOptions, ForkResult, IdleListener, IdleNotification, IdleReason, InProcessRunnerOptions, RunnerState, SpawnOptions, SpawnResult, } from './pack/coordination-types.js';
+export { createPackAsync } from './pack/create-pack-async.js';
+export { FencedBlockDriver } from './pack/driver.js';
+export { executeFlow, executeFlowStream } from './pack/flow.js';
+export { IdleBus } from './pack/idle-bus.js';
+export { InProcessRunner } from './pack/in-process-runner.js';
+export type { PackRuntimeConfigSnapshot } from './pack/pack.js';
+export { createPack, Pack } from './pack/pack.js';
+export type { MeshDeliveryErrorEvent, MeshEntry, MeshMessage, MeshPresenceEvent, MeshRequestOptions, RemoteMeshEntry, } from './pack/pack-mesh.js';
+export { PackMesh } from './pack/pack-mesh.js';
+export { createCodeReview, createDebateDecide, createExplorePlanExecute, createMapReduce, createResearchSynthesize, } from './pack/presets/index.js';
+export type { CodeReviewOptions, DebateDecideOptions, ExplorePlanExecuteOptions, MapReduceOptions, PresetFlowOverrides, ResearchSynthesizeOptions, } from './pack/presets/types.js';
+export type { DelegationPayload } from './pack/protocol.js';
+export { buildDelegationPayload, DELEGATION_PROTOCOL_VERSION, DelegationEntrySchema, DelegationPayloadSchema, DelegationProtocolMismatchError, parseDelegationPayload, } from './pack/protocol.js';
+export { WorkerRegistry } from './pack/registry.js';
+export { StructuredDelegationDriver } from './pack/structured-driver.js';
+export type { AgentWorkerConfig, CustomWorkerConfig, DelegationDriver, DelegationEntry, DelegationParseResult, DelegationRoundRecord, LocalWorkerConfig, McpServerConfig, McpServerTransport, PackErrorCode, PackEvent, PackLeaderConfig, PackOptions, PackResult, PackSendParams, PackSession, PackSharedContext, PackToolsConfig, PackWorkerConfig, RemoteWorkerConfig, WorkerAgentHandle, WorkerEntry, WorkerInspection, } from './pack/types.js';
+export { PackCancelledError, PackError } from './pack/types.js';
+//# sourceMappingURL=pack.d.ts.map

package/dist/runtime/orchestration/pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack.d.ts","sourceRoot":"","sources":["../../../src/runtime/orchestration/pack.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,cAAc,EACd,WAAW,EACX,UAAU,GACX,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,sBAAsB,EACtB,WAAW,EACX,YAAY,EACZ,WAAW,GACZ,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAC9D,YAAY,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EACV,sBAAsB,EACtB,SAAS,EACT,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,eAAe,EACf,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACV,iBAAiB,EACjB,mBAAmB,EACnB,yBAAyB,EACzB,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,uBAAuB,EACvB,+BAA+B,EAC/B,sBAAsB,GACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/runtime/orchestration/pack.js

@@ -0,0 +1,60 @@
+import {
+  buildAgentTree,
+  forkSession,
+  spawnAgent
+} from "./pack/coordination.js";
+import { createPackAsync } from "./pack/create-pack-async.js";
+import { FencedBlockDriver } from "./pack/driver.js";
+import { executeFlow, executeFlowStream } from "./pack/flow.js";
+import { IdleBus } from "./pack/idle-bus.js";
+import { InProcessRunner } from "./pack/in-process-runner.js";
+import { createPack, Pack } from "./pack/pack.js";
+import { PackMesh } from "./pack/pack-mesh.js";
+import {
+  createCodeReview,
+  createDebateDecide,
+  createExplorePlanExecute,
+  createMapReduce,
+  createResearchSynthesize
+} from "./pack/presets/index.js";
+import {
+  buildDelegationPayload,
+  DELEGATION_PROTOCOL_VERSION,
+  DelegationEntrySchema,
+  DelegationPayloadSchema,
+  DelegationProtocolMismatchError,
+  parseDelegationPayload
+} from "./pack/protocol.js";
+import { WorkerRegistry } from "./pack/registry.js";
+import { StructuredDelegationDriver } from "./pack/structured-driver.js";
+import { PackCancelledError, PackError } from "./pack/types.js";
+export {
+  DELEGATION_PROTOCOL_VERSION,
+  DelegationEntrySchema,
+  DelegationPayloadSchema,
+  DelegationProtocolMismatchError,
+  FencedBlockDriver,
+  IdleBus,
+  InProcessRunner,
+  Pack,
+  PackCancelledError,
+  PackError,
+  PackMesh,
+  StructuredDelegationDriver,
+  WorkerRegistry,
+  buildAgentTree,
+  buildDelegationPayload,
+  createCodeReview,
+  createDebateDecide,
+  createExplorePlanExecute,
+  createMapReduce,
+  createPack,
+  createPackAsync,
+  createResearchSynthesize,
+  executeFlow,
+  executeFlowStream,
+  forkSession,
+  parseDelegationPayload,
+  spawnAgent
+};
+//# sourceMappingURL=pack.js.map

package/dist/runtime/orchestration/pack.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/runtime/orchestration/pack.ts"],
+  "sourcesContent": ["// Barrel re-export \u2014 all pack functionality is split across pack/*.ts modules.\n// This file exists so that `import { ... } from './pack.js'` continues to work.\n\nexport {\n  buildAgentTree,\n  forkSession,\n  spawnAgent,\n} from './pack/coordination.js';\nexport type {\n  CoordinationEvent,\n  CoordinationEventKind,\n  ForkInheritOptions,\n  ForkOptions,\n  ForkResult,\n  IdleListener,\n  IdleNotification,\n  IdleReason,\n  InProcessRunnerOptions,\n  RunnerState,\n  SpawnOptions,\n  SpawnResult,\n} from './pack/coordination-types.js';\nexport { createPackAsync } from './pack/create-pack-async.js';\nexport { FencedBlockDriver } from './pack/driver.js';\nexport { executeFlow, executeFlowStream } from './pack/flow.js';\nexport { IdleBus } from './pack/idle-bus.js';\nexport { InProcessRunner } from './pack/in-process-runner.js';\nexport type { PackRuntimeConfigSnapshot } from './pack/pack.js';\nexport { createPack, Pack } from './pack/pack.js';\nexport type {\n  MeshDeliveryErrorEvent,\n  MeshEntry,\n  MeshMessage,\n  MeshPresenceEvent,\n  MeshRequestOptions,\n  RemoteMeshEntry,\n} from './pack/pack-mesh.js';\nexport { PackMesh } from './pack/pack-mesh.js';\nexport {\n  createCodeReview,\n  createDebateDecide,\n  createExplorePlanExecute,\n  createMapReduce,\n  createResearchSynthesize,\n} from './pack/presets/index.js';\nexport type {\n  CodeReviewOptions,\n  DebateDecideOptions,\n  ExplorePlanExecuteOptions,\n  MapReduceOptions,\n  PresetFlowOverrides,\n  ResearchSynthesizeOptions,\n} from './pack/presets/types.js';\nexport type { DelegationPayload } from './pack/protocol.js';\nexport {\n  buildDelegationPayload,\n  DELEGATION_PROTOCOL_VERSION,\n  DelegationEntrySchema,\n  DelegationPayloadSchema,\n  DelegationProtocolMismatchError,\n  parseDelegationPayload,\n} from './pack/protocol.js';\nexport { WorkerRegistry } from './pack/registry.js';\nexport { StructuredDelegationDriver } from './pack/structured-driver.js';\nexport type {\n  AgentWorkerConfig,\n  CustomWorkerConfig,\n  DelegationDriver,\n  DelegationEntry,\n  DelegationParseResult,\n  DelegationRoundRecord,\n  LocalWorkerConfig,\n  McpServerConfig,\n  McpServerTransport,\n  PackErrorCode,\n  PackEvent,\n  PackLeaderConfig,\n  PackOptions,\n  PackResult,\n  PackSendParams,\n  PackSession,\n  PackSharedContext,\n  PackToolsConfig,\n  PackWorkerConfig,\n  RemoteWorkerConfig,\n  WorkerAgentHandle,\n  WorkerEntry,\n  WorkerInspection,\n} from './pack/types.js';\nexport { PackCancelledError, PackError } from './pack/types.js';\n"],
+  "mappings": "AAGA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAeP,SAAS,uBAAuB;AAChC,SAAS,yBAAyB;AAClC,SAAS,aAAa,yBAAyB;AAC/C,SAAS,eAAe;AACxB,SAAS,uBAAuB;AAEhC,SAAS,YAAY,YAAY;AASjC,SAAS,gBAAgB;AACzB;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAUP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,SAAS,sBAAsB;AAC/B,SAAS,kCAAkC;AA0B3C,SAAS,oBAAoB,iBAAiB;",
+  "names": []
+}

package/dist/runtime/orchestration/run/cron-source.d.ts

@@ -0,0 +1,25 @@
+import type { IsolationStrategy, LoopConfig, LoopExecutor, RunEvent, TaskConfig, TaskSource } from './types.js';
+interface CronExpression {
+    minute: number[];
+    hour: number[];
+    dayOfMonth: number[];
+    month: number[];
+    dayOfWeek: number[];
+}
+export interface CronTaskSourceConfig {
+    schedule: string;
+    message: string | ((tick: number) => string);
+    maxEmissions?: number;
+}
+interface CronBatchOptions {
+    signal?: AbortSignal;
+}
+export declare function parseCronSchedule(expression: string): CronExpression;
+export declare function getNextCronDate(schedule: string, from?: Date): Date;
+type CronTaskSource = Extract<TaskSource, {
+    type: 'cron';
+}>;
+export declare function createCronSource(config: CronTaskSourceConfig): CronTaskSource;
+export declare function runCronBatchStream(executor: LoopExecutor, taskConfig: TaskConfig, loopConfig: LoopConfig, baseContextId: string, strategy: IsolationStrategy, options?: CronBatchOptions): AsyncGenerator<RunEvent>;
+export {};
+//# sourceMappingURL=cron-source.d.ts.map

package/dist/runtime/orchestration/run/cron-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron-source.d.ts","sourceRoot":"","sources":["../../../../src/runtime/orchestration/run/cron-source.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAIV,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,QAAQ,EAER,UAAU,EAEV,UAAU,EAEX,MAAM,YAAY,CAAC;AACpB,UAAU,cAAc;IACtB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,UAAU,gBAAgB;IACxB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AA2DD,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAkCpE;AAaD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,CAiBnE;AACD,KAAK,cAAc,GAAG,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE5D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CAS7E;AAmBD,wBAAuB,kBAAkB,CACvC,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,UAAU,EACtB,UAAU,EAAE,UAAU,EACtB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,CAAC,EAAE,gBAAgB,GACzB,cAAc,CAAC,QAAQ,CAAC,CA6J1B"}

package/dist/runtime/orchestration/run/cron-source.js

@@ -0,0 +1,259 @@
+import crypto from "node:crypto";
+import { composeSignals } from "../../../utils/signals.js";
+import { buildLoopResult, runLoopStream } from "./loop-engine.js";
+import {
+  buildTaskBranchInfo,
+  isTaskOutcomeFailure
+} from "./task-batch-helpers.js";
+function parseField(field, min, max, label) {
+  const values = /* @__PURE__ */ new Set();
+  for (const segment of field.split(",")) {
+    const part = segment.trim();
+    if (!part) throw new Error(`Invalid cron ${label} field`);
+    const [base = "", stepStr] = part.split("/");
+    const step = stepStr ? parseInt(stepStr, 10) : 1;
+    if (!Number.isInteger(step) || step <= 0) {
+      throw new Error(`Invalid cron ${label} step: "${part}"`);
+    }
+    let start;
+    let end;
+    if (base === "*") {
+      start = min;
+      end = max;
+    } else {
+      const rangeMatch = base.match(/^(\d+)-(\d+)$/);
+      if (rangeMatch) {
+        const startStr = rangeMatch[1];
+        const endStr = rangeMatch[2];
+        if (startStr === void 0 || endStr === void 0) {
+          throw new Error(`Invalid cron ${label} value: "${part}"`);
+        }
+        start = parseInt(startStr, 10);
+        end = parseInt(endStr, 10);
+      } else {
+        const num = parseInt(base, 10);
+        if (isNaN(num)) {
+          throw new Error(`Invalid cron ${label} value: "${part}"`);
+        }
+        start = num;
+        end = num;
+      }
+    }
+    if (start < min || end > max || start > end) {
+      throw new Error(
+        `Cron ${label} out of range: "${part}" (valid: ${min}-${max})`
+      );
+    }
+    for (let i = start; i <= end; i += step) {
+      values.add(i);
+    }
+  }
+  return [...values].sort((a, b) => a - b);
+}
+function parseCronSchedule(expression) {
+  const fields = expression.trim().split(/\s+/);
+  if (fields.length < 5 || fields.length > 6) {
+    throw new Error(
+      `Invalid cron expression: expected 5 fields, got ${fields.length} \u2014 "${expression}"`
+    );
+  }
+  const parts = fields.length === 6 ? fields.slice(1) : fields;
+  const minuteField = parts[0];
+  const hourField = parts[1];
+  const dayOfMonthField = parts[2];
+  const monthField = parts[3];
+  const dayOfWeekField = parts[4];
+  if (minuteField === void 0 || hourField === void 0 || dayOfMonthField === void 0 || monthField === void 0 || dayOfWeekField === void 0) {
+    throw new Error(
+      `Invalid cron expression: expected 5 fields, got ${parts.length} \u2014 "${expression}"`
+    );
+  }
+  return {
+    minute: parseField(minuteField, 0, 59, "minute"),
+    hour: parseField(hourField, 0, 23, "hour"),
+    dayOfMonth: parseField(dayOfMonthField, 1, 31, "day-of-month"),
+    month: parseField(monthField, 1, 12, "month"),
+    dayOfWeek: parseField(dayOfWeekField, 0, 6, "day-of-week")
+  };
+}
+const MAX_SEARCH_MINUTES = 263e4;
+function matchesCron(date, expr) {
+  return expr.minute.includes(date.getUTCMinutes()) && expr.hour.includes(date.getUTCHours()) && expr.dayOfMonth.includes(date.getUTCDate()) && expr.month.includes(date.getUTCMonth() + 1) && expr.dayOfWeek.includes(date.getUTCDay());
+}
+function getNextCronDate(schedule, from) {
+  const expr = parseCronSchedule(schedule);
+  const start = from ? new Date(from.getTime()) : /* @__PURE__ */ new Date();
+  start.setUTCSeconds(0, 0);
+  start.setUTCMinutes(start.getUTCMinutes() + 1);
+  const candidate = new Date(start.getTime());
+  for (let i = 0; i < MAX_SEARCH_MINUTES; i++) {
+    if (matchesCron(candidate, expr)) {
+      return candidate;
+    }
+    candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);
+  }
+  throw new Error(`No matching cron date found for "${schedule}"`);
+}
+function createCronSource(config) {
+  parseCronSchedule(config.schedule);
+  return {
+    type: "cron",
+    schedule: config.schedule,
+    message: config.message,
+    maxEmissions: config.maxEmissions
+  };
+}
+function waitMs(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("Aborted"));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(new Error("Aborted"));
+      },
+      { once: true }
+    );
+  });
+}
+async function* runCronBatchStream(executor, taskConfig, loopConfig, baseContextId, strategy, options) {
+  const source = taskConfig.source;
+  const maxEmissions = source.maxEmissions ?? 1;
+  const maxTasks = taskConfig.maxTasks != null ? Math.min(maxEmissions, taskConfig.maxTasks) : maxEmissions;
+  let completedTasks = 0;
+  let failedTasks = 0;
+  let lastDate = /* @__PURE__ */ new Date();
+  const batchSignal = options?.signal;
+  for (let tick = 0; tick < maxTasks; tick++) {
+    if (batchSignal?.aborted) break;
+    const nextDate = getNextCronDate(source.schedule, lastDate);
+    const delayMs = nextDate.getTime() - Date.now();
+    if (delayMs > 0) {
+      try {
+        await waitMs(delayMs, batchSignal);
+      } catch {
+        break;
+      }
+    }
+    lastDate = nextDate;
+    const message = typeof source.message === "function" ? source.message(tick + 1) : source.message;
+    const task = { id: crypto.randomUUID(), message };
+    yield {
+      kind: "task-start",
+      source: "task-batch",
+      task: message,
+      index: tick
+    };
+    await taskConfig.onTaskStart?.(message, tick);
+    let handle = { contextId: baseContextId };
+    let cleanupError;
+    let branch;
+    try {
+      handle = await strategy.before(task, tick, baseContextId);
+      const perTaskConfig = batchSignal ? {
+        ...loopConfig,
+        signal: loopConfig.signal ? composeSignals(batchSignal, loopConfig.signal) : batchSignal
+      } : loopConfig;
+      let lastResult;
+      let finalReason = "cancelled";
+      let finalIterations = 0;
+      let finalElapsedMs = 0;
+      let finalCost;
+      let finalOutcomeClass;
+      const startTime = Date.now();
+      const wrappedExecutor = async (msg, ctx, iteration) => {
+        const result2 = await executor(msg, ctx, iteration);
+        lastResult = result2;
+        return result2;
+      };
+      for await (const event of runLoopStream(
+        wrappedExecutor,
+        message,
+        handle.contextId,
+        perTaskConfig
+      )) {
+        yield event;
+        if (event.kind === "loop-terminated") {
+          finalReason = event.reason;
+          finalIterations = event.totalIterations;
+          finalElapsedMs = event.totalElapsedMs;
+          finalCost = event.totalCost;
+          finalOutcomeClass = event.outcomeClass;
+        }
+      }
+      const result = buildLoopResult(
+        lastResult,
+        finalReason,
+        finalIterations,
+        finalElapsedMs || Date.now() - startTime,
+        handle.contextId,
+        finalCost,
+        finalOutcomeClass
+      );
+      if (isTaskOutcomeFailure(result)) {
+        failedTasks++;
+        cleanupError = new Error(
+          `Task terminated: ${result.terminationReason}`
+        );
+        branch = await buildTaskBranchInfo(handle);
+        yield {
+          kind: "task-failed",
+          source: "task-batch",
+          task: message,
+          index: tick,
+          error: `loop failed: ${result.terminationReason}`,
+          branch
+        };
+      } else {
+        completedTasks++;
+        await strategy.after(handle, result);
+        await taskConfig.onTaskComplete?.(message, tick, result);
+        branch = await buildTaskBranchInfo(handle);
+        yield {
+          kind: "task-complete",
+          source: "task-batch",
+          task: message,
+          index: tick,
+          result,
+          branch
+        };
+      }
+    } catch (err) {
+      cleanupError = err instanceof Error ? err : new Error(String(err));
+      failedTasks++;
+      branch ??= await buildTaskBranchInfo(handle);
+      yield {
+        kind: "task-failed",
+        source: "task-batch",
+        task: message,
+        index: tick,
+        error: cleanupError.message,
+        branch
+      };
+    } finally {
+      try {
+        await strategy.cleanup(handle, cleanupError);
+      } catch {
+      }
+    }
+  }
+  const totalTasks = completedTasks + failedTasks;
+  yield {
+    kind: "task-batch-complete",
+    source: "task-batch",
+    totalTasks,
+    completedTasks,
+    failedTasks
+  };
+}
+export {
+  createCronSource,
+  getNextCronDate,
+  parseCronSchedule,
+  runCronBatchStream
+};
+//# sourceMappingURL=cron-source.js.map

package/dist/runtime/orchestration/run/cron-source.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/runtime/orchestration/run/cron-source.ts"],
+  "sourcesContent": ["import crypto from 'node:crypto';\n\nimport { composeSignals } from '../../../utils/signals.js';\nimport { buildLoopResult, runLoopStream } from './loop-engine.js';\nimport {\n  buildTaskBranchInfo,\n  isTaskOutcomeFailure,\n} from './task-batch-helpers.js';\nimport type {\n  BridgeLoopResult,\n  BridgeTaskResult,\n  IsolationHandle,\n  IsolationStrategy,\n  LoopConfig,\n  LoopExecutor,\n  RunEvent,\n  TaskBranchInfo,\n  TaskConfig,\n  TaskItem,\n  TaskSource,\n  TerminationReason,\n} from './types.js';\ninterface CronExpression {\n  minute: number[];\n  hour: number[];\n  dayOfMonth: number[];\n  month: number[];\n  dayOfWeek: number[];\n}\n\nexport interface CronTaskSourceConfig {\n  schedule: string;\n  message: string | ((tick: number) => string);\n  maxEmissions?: number;\n}\n\ninterface CronBatchOptions {\n  signal?: AbortSignal;\n}\nfunction parseField(\n  field: string,\n  min: number,\n  max: number,\n  label: string\n): number[] {\n  const values = new Set<number>();\n\n  for (const segment of field.split(',')) {\n    const part = segment.trim();\n    if (!part) throw new Error(`Invalid cron ${label} field`);\n\n    const [base = '', stepStr] = part.split('/');\n    const step = stepStr ? parseInt(stepStr, 10) : 1;\n    if (!Number.isInteger(step) || step <= 0) {\n      throw new Error(`Invalid cron ${label} step: \"${part}\"`);\n    }\n\n    let start: number;\n    let end: number;\n\n    if (base === '*') {\n      start = min;\n      end = max;\n    } else {\n      const rangeMatch = base.match(/^(\\d+)-(\\d+)$/);\n      if (rangeMatch) {\n        const startStr = rangeMatch[1];\n        const endStr = rangeMatch[2];\n        if (startStr === undefined || endStr === undefined) {\n          throw new Error(`Invalid cron ${label} value: \"${part}\"`);\n        }\n        start = parseInt(startStr, 10);\n        end = parseInt(endStr, 10);\n      } else {\n        const num = parseInt(base, 10);\n        if (isNaN(num)) {\n          throw new Error(`Invalid cron ${label} value: \"${part}\"`);\n        }\n        start = num;\n        end = num;\n      }\n    }\n\n    if (start < min || end > max || start > end) {\n      throw new Error(\n        `Cron ${label} out of range: \"${part}\" (valid: ${min}-${max})`\n      );\n    }\n\n    for (let i = start; i <= end; i += step) {\n      values.add(i);\n    }\n  }\n\n  return [...values].sort((a, b) => a - b);\n}\n\nexport function parseCronSchedule(expression: string): CronExpression {\n  const fields = expression.trim().split(/\\s+/);\n  if (fields.length < 5 || fields.length > 6) {\n    throw new Error(\n      `Invalid cron expression: expected 5 fields, got ${fields.length} \u2014 \"${expression}\"`\n    );\n  }\n\n  const parts = fields.length === 6 ? fields.slice(1) : fields;\n\n  const minuteField = parts[0];\n  const hourField = parts[1];\n  const dayOfMonthField = parts[2];\n  const monthField = parts[3];\n  const dayOfWeekField = parts[4];\n  if (\n    minuteField === undefined ||\n    hourField === undefined ||\n    dayOfMonthField === undefined ||\n    monthField === undefined ||\n    dayOfWeekField === undefined\n  ) {\n    throw new Error(\n      `Invalid cron expression: expected 5 fields, got ${parts.length} \u2014 \"${expression}\"`\n    );\n  }\n\n  return {\n    minute: parseField(minuteField, 0, 59, 'minute'),\n    hour: parseField(hourField, 0, 23, 'hour'),\n    dayOfMonth: parseField(dayOfMonthField, 1, 31, 'day-of-month'),\n    month: parseField(monthField, 1, 12, 'month'),\n    dayOfWeek: parseField(dayOfWeekField, 0, 6, 'day-of-week'),\n  };\n}\nconst MAX_SEARCH_MINUTES = 2_630_000;\n\nfunction matchesCron(date: Date, expr: CronExpression): boolean {\n  return (\n    expr.minute.includes(date.getUTCMinutes()) &&\n    expr.hour.includes(date.getUTCHours()) &&\n    expr.dayOfMonth.includes(date.getUTCDate()) &&\n    expr.month.includes(date.getUTCMonth() + 1) &&\n    expr.dayOfWeek.includes(date.getUTCDay())\n  );\n}\n\nexport function getNextCronDate(schedule: string, from?: Date): Date {\n  const expr = parseCronSchedule(schedule);\n  const start = from ? new Date(from.getTime()) : new Date();\n\n  start.setUTCSeconds(0, 0);\n  start.setUTCMinutes(start.getUTCMinutes() + 1);\n\n  const candidate = new Date(start.getTime());\n\n  for (let i = 0; i < MAX_SEARCH_MINUTES; i++) {\n    if (matchesCron(candidate, expr)) {\n      return candidate;\n    }\n    candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);\n  }\n\n  throw new Error(`No matching cron date found for \"${schedule}\"`);\n}\ntype CronTaskSource = Extract<TaskSource, { type: 'cron' }>;\n\nexport function createCronSource(config: CronTaskSourceConfig): CronTaskSource {\n  parseCronSchedule(config.schedule);\n\n  return {\n    type: 'cron',\n    schedule: config.schedule,\n    message: config.message,\n    maxEmissions: config.maxEmissions,\n  };\n}\nfunction waitMs(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve, reject) => {\n    if (signal?.aborted) {\n      reject(new Error('Aborted'));\n      return;\n    }\n    const timer = setTimeout(resolve, ms);\n    signal?.addEventListener(\n      'abort',\n      () => {\n        clearTimeout(timer);\n        reject(new Error('Aborted'));\n      },\n      { once: true }\n    );\n  });\n}\n\nexport async function* runCronBatchStream(\n  executor: LoopExecutor,\n  taskConfig: TaskConfig,\n  loopConfig: LoopConfig,\n  baseContextId: string,\n  strategy: IsolationStrategy,\n  options?: CronBatchOptions\n): AsyncGenerator<RunEvent> {\n  const source = taskConfig.source as CronTaskSource;\n  const maxEmissions = source.maxEmissions ?? 1;\n  const maxTasks =\n    taskConfig.maxTasks != null\n      ? Math.min(maxEmissions, taskConfig.maxTasks)\n      : maxEmissions;\n\n  let completedTasks = 0;\n  let failedTasks = 0;\n  let lastDate = new Date();\n  const batchSignal = options?.signal;\n\n  for (let tick = 0; tick < maxTasks; tick++) {\n    if (batchSignal?.aborted) break;\n\n    const nextDate = getNextCronDate(source.schedule, lastDate);\n    const delayMs = nextDate.getTime() - Date.now();\n\n    if (delayMs > 0) {\n      try {\n        await waitMs(delayMs, batchSignal);\n      } catch {\n        break;\n      }\n    }\n\n    lastDate = nextDate;\n\n    const message =\n      typeof source.message === 'function'\n        ? source.message(tick + 1)\n        : source.message;\n\n    const task: TaskItem = { id: crypto.randomUUID(), message };\n\n    yield {\n      kind: 'task-start',\n      source: 'task-batch',\n      task: message,\n      index: tick,\n    };\n    await taskConfig.onTaskStart?.(message, tick);\n\n    let handle: IsolationHandle = { contextId: baseContextId };\n    let cleanupError: Error | undefined;\n    let branch: TaskBranchInfo | undefined;\n\n    try {\n      handle = await strategy.before(task, tick, baseContextId);\n\n      const perTaskConfig: LoopConfig = batchSignal\n        ? {\n            ...loopConfig,\n            signal: loopConfig.signal\n              ? composeSignals(batchSignal, loopConfig.signal)\n              : batchSignal,\n          }\n        : loopConfig;\n\n      let lastResult: BridgeTaskResult | undefined;\n      let finalReason: TerminationReason = 'cancelled';\n      let finalIterations = 0;\n      let finalElapsedMs = 0;\n      let finalCost: number | undefined;\n      let finalOutcomeClass: BridgeLoopResult['outcomeClass'];\n      const startTime = Date.now();\n\n      const wrappedExecutor: LoopExecutor = async (msg, ctx, iteration) => {\n        const result = await executor(msg, ctx, iteration);\n        lastResult = result;\n        return result;\n      };\n\n      for await (const event of runLoopStream(\n        wrappedExecutor,\n        message,\n        handle.contextId,\n        perTaskConfig\n      )) {\n        yield event;\n        if (event.kind === 'loop-terminated') {\n          finalReason = event.reason;\n          finalIterations = event.totalIterations;\n          finalElapsedMs = event.totalElapsedMs;\n          finalCost = event.totalCost;\n          finalOutcomeClass = event.outcomeClass;\n        }\n      }\n\n      const result = buildLoopResult(\n        lastResult,\n        finalReason,\n        finalIterations,\n        finalElapsedMs || Date.now() - startTime,\n        handle.contextId,\n        finalCost,\n        finalOutcomeClass\n      );\n\n      if (isTaskOutcomeFailure(result)) {\n        failedTasks++;\n        cleanupError = new Error(\n          `Task terminated: ${result.terminationReason}`\n        );\n        branch = await buildTaskBranchInfo(handle);\n        yield {\n          kind: 'task-failed',\n          source: 'task-batch',\n          task: message,\n          index: tick,\n          error: `loop failed: ${result.terminationReason}`,\n          branch,\n        };\n      } else {\n        completedTasks++;\n        await strategy.after(handle, result);\n        await taskConfig.onTaskComplete?.(message, tick, result);\n        branch = await buildTaskBranchInfo(handle);\n        yield {\n          kind: 'task-complete',\n          source: 'task-batch',\n          task: message,\n          index: tick,\n          result,\n          branch,\n        };\n      }\n    } catch (err) {\n      cleanupError = err instanceof Error ? err : new Error(String(err));\n      failedTasks++;\n      branch ??= await buildTaskBranchInfo(handle);\n      yield {\n        kind: 'task-failed',\n        source: 'task-batch',\n        task: message,\n        index: tick,\n        error: cleanupError.message,\n        branch,\n      };\n    } finally {\n      try {\n        await strategy.cleanup(handle, cleanupError);\n      } catch {\n        /* ignore cleanup errors */\n      }\n    }\n  }\n\n  const totalTasks = completedTasks + failedTasks;\n  yield {\n    kind: 'task-batch-complete',\n    source: 'task-batch',\n    totalTasks,\n    completedTasks,\n    failedTasks,\n  };\n}\n"],
+  "mappings": "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",
+  "names": ["result"]
+}

package/dist/runtime/orchestration/run/event-types.d.ts

@@ -0,0 +1,91 @@
+import type { BridgeSendResult } from '../../../domain/bridge-api.js';
+export type BridgeTaskResult = Extract<BridgeSendResult, {
+    kind: 'task';
+}>;
+export interface StepOutput {
+    text: string;
+    metadata?: Record<string, unknown>;
+    bridgeResult?: BridgeTaskResult;
+}
+export type TerminationReason = 'completion-promise' | 'max-iterations' | 'max-runtime' | 'max-cost' | 'consecutive-failures' | 'stale-loop' | 'stale-progress' | 'stop-condition' | 'cancelled' | 'paused' | 'error';
+export type LoopOutcomeClass = 'success' | 'incomplete' | 'failure' | 'cancelled';
+export interface LoopResultFields {
+    terminationReason: TerminationReason;
+    outcomeClass?: LoopOutcomeClass;
+    totalIterations: number;
+    totalElapsedMs: number;
+    totalCost?: number;
+}
+export type BridgeLoopResult = BridgeTaskResult & LoopResultFields;
+export type FlowTerminationReason = 'end' | 'max-iterations';
+export interface TaskBranchInfo {
+    branchName: string;
+    baseCommit: string;
+    commitCount: number;
+}
+export type RunEvent = {
+    kind: 'loop-iteration';
+    source: 'loop';
+    iteration: number;
+    elapsedMs: number;
+} | {
+    kind: 'loop-terminated';
+    source: 'loop';
+    reason: TerminationReason;
+    outcomeClass: LoopOutcomeClass;
+    totalIterations: number;
+    totalElapsedMs: number;
+    totalCost?: number;
+} | {
+    kind: 'loop-paused';
+    source: 'loop';
+    iteration: number;
+    contextId: string;
+} | {
+    kind: 'task-start';
+    source: 'task-batch';
+    task: string;
+    index: number;
+} | {
+    kind: 'task-complete';
+    source: 'task-batch';
+    task: string;
+    index: number;
+    result: LoopResultFields;
+    branch?: TaskBranchInfo;
+} | {
+    kind: 'task-failed';
+    source: 'task-batch';
+    task: string;
+    index: number;
+    error: string;
+    branch?: TaskBranchInfo;
+} | {
+    kind: 'task-batch-complete';
+    source: 'task-batch';
+    totalTasks: number;
+    completedTasks: number;
+    failedTasks: number;
+} | {
+    kind: 'task-batch-truncated';
+    source: 'task-batch';
+    totalItems: number;
+    maxTasks: number;
+} | {
+    kind: 'flow-step-start';
+    source: 'flow';
+    step: string;
+    iteration: number;
+} | {
+    kind: 'flow-step-complete';
+    source: 'flow';
+    step: string;
+    result: StepOutput;
+} | {
+    kind: 'flow-terminated';
+    source: 'flow';
+    reason: FlowTerminationReason;
+    totalIterations: number;
+    result: StepOutput;
+};
+//# sourceMappingURL=event-types.d.ts.map

package/dist/runtime/orchestration/run/event-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-types.d.ts","sourceRoot":"","sources":["../../../../src/runtime/orchestration/run/event-types.ts"],"names":[],"mappings":"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"}

package/dist/runtime/orchestration/run/event-types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=event-types.js.map

package/dist/runtime/orchestration/run/event-types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/runtime/orchestration/run/flow-engine-graph.d.ts

@@ -0,0 +1,10 @@
+import type { FlowContext, FlowEdge, StepOutput } from './types.js';
+export declare function resolveNextSteps(edge: FlowEdge, result: StepOutput, ctx: FlowContext): string[];
+export declare function resolveStartSteps(edges: FlowEdge[]): string[];
+/**
+ * Design Gap 1 — Cycle detection at construction time.
+ * Inspects static edges (string `to`) only; dynamic edges cannot be checked
+ * statically. Throws if a cycle is reachable from any START step.
+ */
+export declare function detectCycles(edges: FlowEdge[]): void;
+//# sourceMappingURL=flow-engine-graph.d.ts.map

package/dist/runtime/orchestration/run/flow-engine-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-engine-graph.d.ts","sourceRoot":"","sources":["../../../../src/runtime/orchestration/run/flow-engine-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEpE,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,UAAU,EAClB,GAAG,EAAE,WAAW,GACf,MAAM,EAAE,CAIV;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,EAAE,CAU7D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,CA6BpD"}

package/dist/runtime/orchestration/run/flow-engine-graph.js

@@ -0,0 +1,47 @@
+function resolveNextSteps(edge, result, ctx) {
+  if (typeof edge.to === "string") return [edge.to];
+  const next = edge.to(result, ctx);
+  return Array.isArray(next) ? next : [next];
+}
+function resolveStartSteps(edges) {
+  const dynamicStart = edges.find(
+    (e) => e.from === "START" && typeof e.to !== "string"
+  );
+  if (dynamicStart) {
+    throw new Error("Flow START edges must target static step names");
+  }
+  return edges.filter((e) => e.from === "START").flatMap((e) => typeof e.to === "string" ? [e.to] : []);
+}
+function detectCycles(edges) {
+  const graph = /* @__PURE__ */ new Map();
+  for (const e of edges) {
+    if (typeof e.to === "string") {
+      const targets = graph.get(e.from) ?? [];
+      targets.push(e.to);
+      graph.set(e.from, targets);
+    }
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const stack = /* @__PURE__ */ new Set();
+  function dfs(node) {
+    if (stack.has(node)) {
+      throw new Error(`Flow cycle detected at step "${node}"`);
+    }
+    if (visited.has(node)) return;
+    stack.add(node);
+    visited.add(node);
+    for (const next of graph.get(node) ?? []) dfs(next);
+    stack.delete(node);
+  }
+  for (const e of edges) {
+    if (e.from === "START" && typeof e.to === "string") {
+      dfs(e.to);
+    }
+  }
+}
+export {
+  detectCycles,
+  resolveNextSteps,
+  resolveStartSteps
+};
+//# sourceMappingURL=flow-engine-graph.js.map

package/dist/runtime/orchestration/run/flow-engine-graph.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/runtime/orchestration/run/flow-engine-graph.ts"],
+  "sourcesContent": ["import type { FlowContext, FlowEdge, StepOutput } from './types.js';\n\nexport function resolveNextSteps(\n  edge: FlowEdge,\n  result: StepOutput,\n  ctx: FlowContext\n): string[] {\n  if (typeof edge.to === 'string') return [edge.to];\n  const next = edge.to(result, ctx);\n  return Array.isArray(next) ? next : [next];\n}\n\nexport function resolveStartSteps(edges: FlowEdge[]): string[] {\n  const dynamicStart = edges.find(\n    (e) => e.from === 'START' && typeof e.to !== 'string'\n  );\n  if (dynamicStart) {\n    throw new Error('Flow START edges must target static step names');\n  }\n  return edges\n    .filter((e) => e.from === 'START')\n    .flatMap((e) => (typeof e.to === 'string' ? [e.to] : []));\n}\n\n/**\n * Design Gap 1 \u2014 Cycle detection at construction time.\n * Inspects static edges (string `to`) only; dynamic edges cannot be checked\n * statically. Throws if a cycle is reachable from any START step.\n */\nexport function detectCycles(edges: FlowEdge[]): void {\n  const graph = new Map<string, string[]>();\n  for (const e of edges) {\n    if (typeof e.to === 'string') {\n      const targets = graph.get(e.from) ?? [];\n      targets.push(e.to);\n      graph.set(e.from, targets);\n    }\n  }\n\n  const visited = new Set<string>();\n  const stack = new Set<string>();\n\n  function dfs(node: string): void {\n    if (stack.has(node)) {\n      throw new Error(`Flow cycle detected at step \"${node}\"`);\n    }\n    if (visited.has(node)) return;\n    stack.add(node);\n    visited.add(node);\n    for (const next of graph.get(node) ?? []) dfs(next);\n    stack.delete(node);\n  }\n\n  for (const e of edges) {\n    if (e.from === 'START' && typeof e.to === 'string') {\n      dfs(e.to);\n    }\n  }\n}\n"],
+  "mappings": "AAEO,SAAS,iBACd,MACA,QACA,KACU;AACV,MAAI,OAAO,KAAK,OAAO,SAAU,QAAO,CAAC,KAAK,EAAE;AAChD,QAAM,OAAO,KAAK,GAAG,QAAQ,GAAG;AAChC,SAAO,MAAM,QAAQ,IAAI,IAAI,OAAO,CAAC,IAAI;AAC3C;AAEO,SAAS,kBAAkB,OAA6B;AAC7D,QAAM,eAAe,MAAM;AAAA,IACzB,CAAC,MAAM,EAAE,SAAS,WAAW,OAAO,EAAE,OAAO;AAAA,EAC/C;AACA,MAAI,cAAc;AAChB,UAAM,IAAI,MAAM,gDAAgD;AAAA,EAClE;AACA,SAAO,MACJ,OAAO,CAAC,MAAM,EAAE,SAAS,OAAO,EAChC,QAAQ,CAAC,MAAO,OAAO,EAAE,OAAO,WAAW,CAAC,EAAE,EAAE,IAAI,CAAC,CAAE;AAC5D;AAOO,SAAS,aAAa,OAAyB;AACpD,QAAM,QAAQ,oBAAI,IAAsB;AACxC,aAAW,KAAK,OAAO;AACrB,QAAI,OAAO,EAAE,OAAO,UAAU;AAC5B,YAAM,UAAU,MAAM,IAAI,EAAE,IAAI,KAAK,CAAC;AACtC,cAAQ,KAAK,EAAE,EAAE;AACjB,YAAM,IAAI,EAAE,MAAM,OAAO;AAAA,IAC3B;AAAA,EACF;AAEA,QAAM,UAAU,oBAAI,IAAY;AAChC,QAAM,QAAQ,oBAAI,IAAY;AAE9B,WAAS,IAAI,MAAoB;AAC/B,QAAI,MAAM,IAAI,IAAI,GAAG;AACnB,YAAM,IAAI,MAAM,gCAAgC,IAAI,GAAG;AAAA,IACzD;AACA,QAAI,QAAQ,IAAI,IAAI,EAAG;AACvB,UAAM,IAAI,IAAI;AACd,YAAQ,IAAI,IAAI;AAChB,eAAW,QAAQ,MAAM,IAAI,IAAI,KAAK,CAAC,EAAG,KAAI,IAAI;AAClD,UAAM,OAAO,IAAI;AAAA,EACnB;AAEA,aAAW,KAAK,OAAO;AACrB,QAAI,EAAE,SAAS,WAAW,OAAO,EAAE,OAAO,UAAU;AAClD,UAAI,EAAE,EAAE;AAAA,IACV;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/runtime/orchestration/run/flow-engine.d.ts

@@ -0,0 +1,6 @@
+import type { FabricAccessor } from '../../bridge/fabric-types.js';
+import type { FlowConfig, FlowRunResult, RunEvent, StepDispatcher, StepOutput } from './types.js';
+export declare function runFlowEngineResult(dispatcher: StepDispatcher, message: string, contextId: string, flow: FlowConfig, fabric?: FabricAccessor): Promise<FlowRunResult>;
+export declare function runFlowEngine(dispatcher: StepDispatcher, message: string, contextId: string, flow: FlowConfig, fabric?: FabricAccessor): Promise<StepOutput>;
+export declare function runFlowEngineStream(dispatcher: StepDispatcher, message: string, contextId: string, flow: FlowConfig, fabric?: FabricAccessor): AsyncGenerator<RunEvent, FlowRunResult, void>;
+//# sourceMappingURL=flow-engine.d.ts.map

package/dist/runtime/orchestration/run/flow-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-engine.d.ts","sourceRoot":"","sources":["../../../../src/runtime/orchestration/run/flow-engine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAMnE,OAAO,KAAK,EACV,UAAU,EAEV,aAAa,EACb,QAAQ,EACR,cAAc,EAEd,UAAU,EACX,MAAM,YAAY,CAAC;AAiYpB,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,cAAc,EAC1B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,UAAU,EAChB,MAAM,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,aAAa,CAAC,CAcxB;AAED,wBAAsB,aAAa,CACjC,UAAU,EAAE,cAAc,EAC1B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,UAAU,EAChB,MAAM,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,UAAU,CAAC,CAErB;AAED,wBAAuB,mBAAmB,CACxC,UAAU,EAAE,cAAc,EAC1B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,UAAU,EAChB,MAAM,CAAC,EAAE,cAAc,GACtB,cAAc,CAAC,QAAQ,EAAE,aAAa,EAAE,IAAI,CAAC,CAc/C"}