@codemation/core 0.0.1

package/src/contracts/workflowTypes.ts

@@ -0,0 +1,280 @@
+import type { TypeToken } from "../di";
+import type { CredentialRequirement } from "./credentialTypes";
+import type { RetryPolicySpec } from "./retryPolicySpec.types";
+
+export type WorkflowId = string;
+export type NodeId = string;
+export type OutputPortKey = string;
+export type InputPortKey = string;
+export type PersistedTokenId = string;
+
+export type NodeKind = "trigger" | "node";
+export type JsonPrimitive = string | number | boolean | null;
+export interface JsonObject {
+  readonly [key: string]: JsonValue;
+}
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+export type JsonArray = ReadonlyArray<JsonValue>;
+
+export interface Edge {
+  from: { nodeId: NodeId; output: OutputPortKey };
+  to: { nodeId: NodeId; input: InputPortKey };
+}
+
+export type NodeConnectionName = string;
+
+/**
+ * Named connection from an executable parent node to child nodes that exist in {@link WorkflowDefinition.nodes}
+ * but are not traversed by the main execution graph.
+ */
+export interface WorkflowNodeConnection {
+  readonly parentNodeId: NodeId;
+  readonly connectionName: NodeConnectionName;
+  readonly childNodeIds: ReadonlyArray<NodeId>;
+}
+
+export interface WorkflowDefinition {
+  id: WorkflowId;
+  name: string;
+  nodes: NodeDefinition[];
+  edges: Edge[];
+  /**
+   * Optional metadata: which nodes are connection-owned children (e.g. AI agent `llm` / `tools` slots).
+   * When omitted, all nodes in {@link nodes} are treated as executable for topology.
+   */
+  readonly connections?: ReadonlyArray<WorkflowNodeConnection>;
+  /** Directory + file-stem path under a workflow discovery root (for UI grouping only). */
+  discoveryPathSegments?: readonly string[];
+  /** Retention for run JSON and binaries (seconds). Host/env may supply defaults when omitted. */
+  readonly prunePolicy?: WorkflowPrunePolicySpec;
+  /** Whether to keep run data after completion. Host/env may supply defaults when omitted. */
+  readonly storagePolicy?: WorkflowStoragePolicySpec;
+  /** Invoked after a node fails permanently (retries exhausted) and node error handler did not recover. */
+  readonly workflowErrorHandler?: WorkflowErrorHandlerSpec;
+}
+
+export interface WorkflowGraph {
+  next(nodeId: NodeId, output: OutputPortKey): ReadonlyArray<Readonly<{ nodeId: NodeId; input: InputPortKey }>>;
+}
+
+export interface WorkflowGraphFactory {
+  create(def: WorkflowDefinition): WorkflowGraph;
+}
+
+export interface NodeConfigBase {
+  readonly kind: NodeKind;
+  readonly type: TypeToken<unknown>;
+  readonly name?: string;
+  readonly id?: NodeId;
+  readonly icon?: string;
+  readonly execution?: Readonly<{ hint?: "local" | "worker"; queue?: string }>;
+  /** In-process execute retries (runnable nodes). Triggers typically omit this. */
+  readonly retryPolicy?: RetryPolicySpec;
+  /** Recover from execute failures; return outputs to continue, or rethrow to fail the node. */
+  readonly nodeErrorHandler?: NodeErrorHandlerSpec;
+  /**
+   * When true, edges carrying zero items on an output port still schedule single-input downstream nodes.
+   * Decided from the **source** node that produced the (empty) output. Default (false/undefined): empty
+   * main batches skip downstream execution and propagate the empty path.
+   */
+  readonly continueWhenEmptyOutput?: boolean;
+  getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
+}
+
+export declare const runnableNodeInputType: unique symbol;
+export declare const runnableNodeOutputType: unique symbol;
+export declare const triggerNodeOutputType: unique symbol;
+
+export interface RunnableNodeConfig<TInputJson = unknown, TOutputJson = unknown> extends NodeConfigBase {
+  readonly kind: "node";
+  readonly [runnableNodeInputType]?: TInputJson;
+  readonly [runnableNodeOutputType]?: TOutputJson;
+}
+
+export declare const triggerNodeSetupStateType: unique symbol;
+
+export interface TriggerNodeConfig<
+  TOutputJson = unknown,
+  TSetupState extends JsonValue | undefined = undefined,
+> extends NodeConfigBase {
+  readonly kind: "trigger";
+  readonly [triggerNodeOutputType]?: TOutputJson;
+  readonly [triggerNodeSetupStateType]?: TSetupState;
+}
+
+export type RunnableNodeInputJson<TConfig extends RunnableNodeConfig<any, any>> =
+  TConfig extends RunnableNodeConfig<infer TInputJson, any> ? TInputJson : never;
+
+export type RunnableNodeOutputJson<TConfig extends RunnableNodeConfig<any, any>> =
+  TConfig extends RunnableNodeConfig<any, infer TOutputJson> ? TOutputJson : never;
+
+export type TriggerNodeOutputJson<TConfig extends TriggerNodeConfig<any, any>> =
+  TConfig extends TriggerNodeConfig<infer TOutputJson, any> ? TOutputJson : never;
+
+export type TriggerNodeSetupState<TConfig extends TriggerNodeConfig<any, any>> =
+  TConfig extends TriggerNodeConfig<any, infer TSetupState> ? TSetupState : never;
+
+export interface NodeDefinition {
+  id: NodeId;
+  kind: NodeKind;
+  type: TypeToken<unknown>;
+  name?: string;
+  config: NodeConfigBase;
+}
+
+export interface NodeRef {
+  id: NodeId;
+  kind: NodeKind;
+  name?: string;
+}
+
+export type PairedItemRef = Readonly<{ nodeId: NodeId; output: OutputPortKey; itemIndex: number }>;
+
+export type BinaryPreviewKind = "image" | "audio" | "video" | "download";
+
+export type BinaryAttachment = Readonly<{
+  id: string;
+  storageKey: string;
+  mimeType: string;
+  size: number;
+  storageDriver: string;
+  previewKind: BinaryPreviewKind;
+  createdAt: string;
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  activationId: NodeActivationId;
+  filename?: string;
+  sha256?: string;
+}>;
+
+export type ItemBinary = Readonly<Record<string, BinaryAttachment>>;
+
+export type Item<TJson = unknown> = Readonly<{
+  json: TJson;
+  binary?: ItemBinary;
+  meta?: Readonly<Record<string, unknown>>;
+  paired?: ReadonlyArray<PairedItemRef>;
+}>;
+
+export type Items<TJson = unknown> = ReadonlyArray<Item<TJson>>;
+
+export type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
+
+export type RunId = string;
+export type NodeActivationId = string;
+
+export interface ParentExecutionRef {
+  runId: RunId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  /** Subworkflow depth of the **spawning** run (0 = root). Passed when starting a child run. */
+  subworkflowDepth?: number;
+  /** Effective max node activations from the parent run (propagated to child policy merge). */
+  engineMaxNodeActivations?: number;
+  /** Effective max subworkflow depth from the parent run (propagated to child policy merge). */
+  engineMaxSubworkflowDepth?: number;
+}
+
+export interface RunDataSnapshot {
+  getOutputs(nodeId: NodeId): NodeOutputs | undefined;
+  getOutputItems(nodeId: NodeId, output?: OutputPortKey): Items;
+  getOutputItem(nodeId: NodeId, itemIndex: number, output?: OutputPortKey): Item | undefined;
+}
+
+export interface MutableRunData extends RunDataSnapshot {
+  setOutputs(nodeId: NodeId, outputs: NodeOutputs): void;
+  dump(): Record<NodeId, NodeOutputs>;
+}
+
+export interface RunDataFactory {
+  create(initial?: Record<NodeId, NodeOutputs>): MutableRunData;
+}
+
+export interface RunIdFactory {
+  makeRunId(): RunId;
+}
+
+export interface ActivationIdFactory {
+  makeActivationId(): NodeActivationId;
+}
+
+export type UpstreamRefPlaceholder = `$${number}`;
+export const branchRef = (index: number) => `$${index}` as UpstreamRefPlaceholder;
+
+export type ExecutionMode = "local" | "worker";
+
+export interface NodeSchedulerDecision {
+  mode: ExecutionMode;
+  queue?: string;
+}
+
+export interface NodeOffloadPolicy {
+  decide(args: { workflowId: WorkflowId; nodeId: NodeId; config: NodeConfigBase }): NodeSchedulerDecision;
+}
+
+/** Whether to persist run execution data after the workflow finishes. */
+export type WorkflowStoragePolicyMode = "ALL" | "SUCCESS" | "ERROR" | "NEVER";
+
+export type WorkflowStoragePolicySpec = WorkflowStoragePolicyMode | TypeToken<WorkflowStoragePolicyResolver>;
+
+export interface WorkflowStoragePolicyResolver {
+  shouldPersist(args: WorkflowStoragePolicyDecisionArgs): boolean | Promise<boolean>;
+}
+
+export interface WorkflowStoragePolicyDecisionArgs {
+  readonly runId: RunId;
+  readonly workflowId: WorkflowId;
+  readonly workflow: WorkflowDefinition;
+  readonly finalStatus: "completed" | "failed";
+  readonly startedAt: string;
+  readonly finishedAt: string;
+}
+
+export interface WorkflowPrunePolicySpec {
+  readonly runDataRetentionSeconds?: number;
+  readonly binaryRetentionSeconds?: number;
+}
+
+export interface PersistedRunPolicySnapshot {
+  readonly retentionSeconds?: number;
+  readonly binaryRetentionSeconds?: number;
+  readonly storagePolicy: WorkflowStoragePolicyMode;
+}
+
+export interface WorkflowErrorHandler {
+  onError(ctx: WorkflowErrorContext): void | Promise<void>;
+}
+
+export interface WorkflowErrorContext {
+  readonly runId: RunId;
+  readonly workflowId: WorkflowId;
+  readonly workflow: WorkflowDefinition;
+  readonly failedNodeId: NodeId;
+  readonly error: Error;
+  readonly startedAt: string;
+  readonly finishedAt: string;
+}
+
+export type WorkflowErrorHandlerSpec = TypeToken<WorkflowErrorHandler> | WorkflowErrorHandler;
+
+export interface NodeErrorHandlerArgs<TConfig extends NodeConfigBase = NodeConfigBase> {
+  readonly kind: "single" | "multi";
+  readonly items: Items;
+  readonly inputsByPort: Readonly<Record<InputPortKey, Items>> | undefined;
+  readonly ctx: import("./runtimeTypes").NodeExecutionContext<TConfig>;
+  readonly error: Error;
+}
+
+export interface NodeErrorHandler {
+  handle<TConfig extends NodeConfigBase>(args: NodeErrorHandlerArgs<TConfig>): Promise<NodeOutputs>;
+}
+
+export type NodeErrorHandlerSpec = TypeToken<NodeErrorHandler> | NodeErrorHandler;
+
+/** Runtime defaults when workflow omits prune/storage fields (typically from host env). */
+export interface WorkflowPolicyRuntimeDefaults {
+  readonly retentionSeconds?: number;
+  readonly binaryRetentionSeconds?: number;
+  readonly storagePolicy?: WorkflowStoragePolicyMode;
+}

package/src/di/CoreTokens.ts

@@ -0,0 +1,60 @@
+import type { TypeToken } from "./index";
+import type { RunEventBus } from "../events/runEvents";
+import type { EngineExecutionLimitsPolicy } from "../policies/executionLimits/EngineExecutionLimitsPolicy";
+import type {
+  ActivationIdFactory,
+  BinaryStorage,
+  CredentialSessionService,
+  CredentialTypeRegistry,
+  ExecutionContextFactory,
+  LiveWorkflowRepository,
+  NodeActivationScheduler,
+  NodeResolver,
+  PersistedWorkflowTokenRegistryLike,
+  RunDataFactory,
+  RunIdFactory,
+  TriggerSetupStateRepository,
+  WorkflowExecutionRepository,
+  WorkflowNodeInstanceFactory,
+  WorkflowActivationPolicy,
+  WorkflowRepository,
+  WorkflowRunnerService,
+} from "../types";
+
+export const CoreTokens = {
+  PersistedWorkflowTokenRegistry: Symbol.for(
+    "codemation.core.PersistedWorkflowTokenRegistry",
+  ) as TypeToken<PersistedWorkflowTokenRegistryLike>,
+  CredentialSessionService: Symbol.for(
+    "codemation.core.CredentialSessionService",
+  ) as TypeToken<CredentialSessionService>,
+  CredentialTypeRegistry: Symbol.for("codemation.core.CredentialTypeRegistry") as TypeToken<CredentialTypeRegistry>,
+  WorkflowRunnerService: Symbol.for("codemation.core.WorkflowRunnerService") as TypeToken<WorkflowRunnerService>,
+  LiveWorkflowRepository: Symbol.for("codemation.core.LiveWorkflowRepository") as TypeToken<LiveWorkflowRepository>,
+  WorkflowRepository: Symbol.for("codemation.core.WorkflowRepository") as TypeToken<WorkflowRepository>,
+  NodeResolver: Symbol.for("codemation.core.NodeResolver") as TypeToken<NodeResolver>,
+  WorkflowNodeInstanceFactory: Symbol.for(
+    "codemation.core.WorkflowNodeInstanceFactory",
+  ) as TypeToken<WorkflowNodeInstanceFactory>,
+  RunIdFactory: Symbol.for("codemation.core.RunIdFactory") as TypeToken<RunIdFactory>,
+  ActivationIdFactory: Symbol.for("codemation.core.ActivationIdFactory") as TypeToken<ActivationIdFactory>,
+  WorkflowExecutionRepository: Symbol.for(
+    "codemation.core.WorkflowExecutionRepository",
+  ) as TypeToken<WorkflowExecutionRepository>,
+  TriggerSetupStateRepository: Symbol.for(
+    "codemation.core.TriggerSetupStateRepository",
+  ) as TypeToken<TriggerSetupStateRepository>,
+  NodeActivationScheduler: Symbol.for("codemation.core.NodeActivationScheduler") as TypeToken<NodeActivationScheduler>,
+  RunDataFactory: Symbol.for("codemation.core.RunDataFactory") as TypeToken<RunDataFactory>,
+  ExecutionContextFactory: Symbol.for("codemation.core.ExecutionContextFactory") as TypeToken<ExecutionContextFactory>,
+  RunEventBus: Symbol.for("codemation.core.RunEventBus") as TypeToken<RunEventBus>,
+  BinaryStorage: Symbol.for("codemation.core.BinaryStorage") as TypeToken<BinaryStorage>,
+  WebhookBasePath: Symbol.for("codemation.core.WebhookBasePath") as TypeToken<string>,
+  /** Engine execution limits (defaults + optional host overrides). Consumers may bind a custom instance to override. */
+  EngineExecutionLimitsPolicy: Symbol.for(
+    "codemation.core.EngineExecutionLimitsPolicy",
+  ) as TypeToken<EngineExecutionLimitsPolicy>,
+  WorkflowActivationPolicy: Symbol.for(
+    "codemation.core.WorkflowActivationPolicy",
+  ) as TypeToken<WorkflowActivationPolicy>,
+} as const;

package/src/di/index.ts

@@ -0,0 +1,24 @@
+import "reflect-metadata";
+
+export { CoreTokens } from "./CoreTokens";
+export {
+  container,
+  delay,
+  inject,
+  injectAll,
+  injectable,
+  instanceCachingFactory,
+  instancePerContainerCachingFactory,
+  predicateAwareClassFactory,
+  registry,
+  singleton,
+} from "tsyringe";
+export type {
+  DependencyContainer as Container,
+  DependencyContainer,
+  Disposable,
+  InjectionToken,
+  Lifecycle,
+  RegistrationOptions,
+  InjectionToken as TypeToken,
+} from "tsyringe";

package/src/events/EventPublishingWorkflowExecutionRepository.ts

@@ -0,0 +1,67 @@
+import type {
+  PersistedRunState,
+  RunId,
+  RunPruneCandidate,
+  RunSummary,
+  WorkflowExecutionListingRepository,
+  WorkflowExecutionPruneRepository,
+  WorkflowExecutionRepository,
+  WorkflowId,
+} from "../types";
+import type { RunEventBus } from "./runEvents";
+
+export class EventPublishingWorkflowExecutionRepository
+  implements WorkflowExecutionRepository, WorkflowExecutionListingRepository, WorkflowExecutionPruneRepository
+{
+  constructor(
+    private readonly inner: WorkflowExecutionRepository,
+    private readonly eventBus: RunEventBus,
+    private readonly now: () => Date = () => new Date(),
+  ) {}
+
+  async createRun(args: Parameters<WorkflowExecutionRepository["createRun"]>[0]): Promise<void> {
+    await this.inner.createRun(args);
+    await this.eventBus.publish({
+      kind: "runCreated",
+      runId: args.runId,
+      workflowId: args.workflowId,
+      parent: args.parent,
+      at: this.now().toISOString(),
+    });
+  }
+
+  async load(runId: RunId): Promise<PersistedRunState | undefined> {
+    return await this.inner.load(runId);
+  }
+
+  async save(state: PersistedRunState): Promise<void> {
+    await this.inner.save(state);
+    await this.eventBus.publish({
+      kind: "runSaved",
+      runId: state.runId,
+      workflowId: state.workflowId,
+      parent: state.parent,
+      at: this.now().toISOString(),
+      state,
+    });
+  }
+
+  async deleteRun(runId: RunId): Promise<void> {
+    if (!this.inner.deleteRun) return;
+    await this.inner.deleteRun(runId);
+  }
+
+  async listRuns(args?: Readonly<{ workflowId?: WorkflowId; limit?: number }>): Promise<ReadonlyArray<RunSummary>> {
+    const listingRepository = this.inner as unknown as Partial<WorkflowExecutionListingRepository>;
+    if (!listingRepository.listRuns) return [];
+    return await listingRepository.listRuns(args);
+  }
+
+  async listRunsOlderThan(
+    args: Readonly<{ beforeIso: string; limit?: number }>,
+  ): Promise<ReadonlyArray<RunPruneCandidate>> {
+    const pruneRepository = this.inner as unknown as Partial<WorkflowExecutionPruneRepository>;
+    if (!pruneRepository.listRunsOlderThan) return [];
+    return await pruneRepository.listRunsOlderThan(args);
+  }
+}

package/src/events/InMemoryRunEventBusRegistry.ts

@@ -0,0 +1,37 @@
+import type { WorkflowId } from "../types";
+
+import type { RunEvent, RunEventBus, RunEventSubscription } from "./runEvents";
+
+import { InMemoryRunEventSubscription } from "./InMemoryRunEventSubscription";
+
+export class InMemoryRunEventBus implements RunEventBus {
+  private readonly globalListeners = new Set<(event: RunEvent) => void>();
+  private readonly listenersByWorkflowId = new Map<WorkflowId, Set<(event: RunEvent) => void>>();
+
+  async publish(event: RunEvent): Promise<void> {
+    for (const listener of this.globalListeners) listener(event);
+    for (const listener of this.listenersByWorkflowId.get(event.workflowId) ?? []) listener(event);
+  }
+
+  async subscribe(onEvent: (event: RunEvent) => void): Promise<RunEventSubscription> {
+    this.globalListeners.add(onEvent);
+    return new InMemoryRunEventSubscription(() => {
+      this.globalListeners.delete(onEvent);
+    });
+  }
+
+  async subscribeToWorkflow(workflowId: WorkflowId, onEvent: (event: RunEvent) => void): Promise<RunEventSubscription> {
+    const existing = this.listenersByWorkflowId.get(workflowId) ?? new Set<(event: RunEvent) => void>();
+    existing.add(onEvent);
+    this.listenersByWorkflowId.set(workflowId, existing);
+
+    return new InMemoryRunEventSubscription(() => {
+      const listeners = this.listenersByWorkflowId.get(workflowId);
+      if (!listeners) return;
+      listeners.delete(onEvent);
+      if (listeners.size === 0) this.listenersByWorkflowId.delete(workflowId);
+    });
+  }
+}
+
+export { InMemoryRunEventSubscription } from "./InMemoryRunEventSubscription";

package/src/events/InMemoryRunEventSubscription.ts

@@ -0,0 +1,9 @@
+import type { RunEventSubscription } from "./runEvents";
+
+export class InMemoryRunEventSubscription implements RunEventSubscription {
+  constructor(private readonly onClose: () => void) {}
+
+  async close(): Promise<void> {
+    this.onClose();
+  }
+}

package/src/events/NodeEventPublisher.ts

@@ -0,0 +1,22 @@
+import type { RunEventBus } from "./runEvents";
+import type { NodeExecutionSnapshot } from "../types";
+
+/** Publishes node lifecycle snapshots onto the run {@link RunEventBus}. */
+export class NodeEventPublisher {
+  constructor(private readonly eventBus: RunEventBus | undefined) {}
+
+  async publish(
+    kind: "nodeQueued" | "nodeStarted" | "nodeCompleted" | "nodeFailed",
+    snapshot: NodeExecutionSnapshot,
+  ): Promise<void> {
+    if (!this.eventBus) return;
+    await this.eventBus.publish({
+      kind,
+      runId: snapshot.runId,
+      workflowId: snapshot.workflowId,
+      parent: snapshot.parent,
+      at: snapshot.updatedAt,
+      snapshot,
+    });
+  }
+}

package/src/events/index.ts

@@ -0,0 +1,4 @@
+export { NodeEventPublisher } from "./NodeEventPublisher";
+export { InMemoryRunEventBus } from "./InMemoryRunEventBusRegistry";
+export { EventPublishingWorkflowExecutionRepository } from "./EventPublishingWorkflowExecutionRepository";
+export * from "./runEvents";

package/src/events/runEvents.ts

@@ -0,0 +1,54 @@
+import type { NodeExecutionSnapshot, ParentExecutionRef, PersistedRunState, RunId, WorkflowId } from "../types";
+
+export type RunEvent =
+  | Readonly<{ kind: "runCreated"; runId: RunId; workflowId: WorkflowId; parent?: ParentExecutionRef; at: string }>
+  | Readonly<{
+      kind: "runSaved";
+      runId: RunId;
+      workflowId: WorkflowId;
+      parent?: ParentExecutionRef;
+      at: string;
+      state: PersistedRunState;
+    }>
+  | Readonly<{
+      kind: "nodeQueued";
+      runId: RunId;
+      workflowId: WorkflowId;
+      parent?: ParentExecutionRef;
+      at: string;
+      snapshot: NodeExecutionSnapshot;
+    }>
+  | Readonly<{
+      kind: "nodeStarted";
+      runId: RunId;
+      workflowId: WorkflowId;
+      parent?: ParentExecutionRef;
+      at: string;
+      snapshot: NodeExecutionSnapshot;
+    }>
+  | Readonly<{
+      kind: "nodeCompleted";
+      runId: RunId;
+      workflowId: WorkflowId;
+      parent?: ParentExecutionRef;
+      at: string;
+      snapshot: NodeExecutionSnapshot;
+    }>
+  | Readonly<{
+      kind: "nodeFailed";
+      runId: RunId;
+      workflowId: WorkflowId;
+      parent?: ParentExecutionRef;
+      at: string;
+      snapshot: NodeExecutionSnapshot;
+    }>;
+
+export interface RunEventSubscription {
+  close(): Promise<void>;
+}
+
+export interface RunEventBus {
+  publish(event: RunEvent): Promise<void>;
+  subscribe(onEvent: (event: RunEvent) => void): Promise<RunEventSubscription>;
+  subscribeToWorkflow(workflowId: WorkflowId, onEvent: (event: RunEvent) => void): Promise<RunEventSubscription>;
+}

package/src/execution/ActivationEnqueueService.ts

@@ -0,0 +1,125 @@
+import type {
+  ConnectionInvocationRecord,
+  EngineRunCounters,
+  NodeActivationRequest,
+  NodeActivationScheduler,
+  NodeExecutionSnapshot,
+  NodeId,
+  ParentExecutionRef,
+  PendingNodeExecution,
+  PersistedRunControlState,
+  RunDataFactory,
+  RunExecutionOptions,
+  RunId,
+  RunQueueEntry,
+  RunResult,
+  WorkflowExecutionRepository,
+  WorkflowId,
+} from "../types";
+
+import { RunQueuePlanner } from "../planning/RunQueuePlanner";
+
+import { NodeEventPublisher } from "../events/NodeEventPublisher";
+import { NodeExecutionSnapshotFactory } from "./NodeExecutionSnapshotFactory";
+import { NodeInputsByPortFactory } from "./NodeInputsByPortFactory";
+
+type PersistedRunStateRecord = NonNullable<Awaited<ReturnType<WorkflowExecutionRepository["load"]>>>;
+
+type ActivationSchedulerPort = Pick<NodeActivationScheduler, "enqueue"> &
+  Pick<Partial<NodeActivationScheduler>, "notifyPendingStatePersisted">;
+
+export type ActivationEnqueueRequest = {
+  runId: RunId;
+  workflowId: WorkflowId;
+  startedAt: string;
+  parent?: ParentExecutionRef;
+  executionOptions?: RunExecutionOptions;
+  control: PersistedRunControlState | undefined;
+  workflowSnapshot: PersistedRunStateRecord["workflowSnapshot"];
+  mutableState: PersistedRunStateRecord["mutableState"];
+  policySnapshot: PersistedRunStateRecord["policySnapshot"];
+  pendingQueue: RunQueueEntry[];
+  request: NodeActivationRequest;
+  previousNodeSnapshotsByNodeId: Record<NodeId, NodeExecutionSnapshot>;
+  planner: RunQueuePlanner;
+  engineCounters?: EngineRunCounters;
+  connectionInvocations?: ReadonlyArray<ConnectionInvocationRecord>;
+};
+
+export class ActivationEnqueueService {
+  constructor(
+    private readonly activationScheduler: ActivationSchedulerPort,
+    private readonly workflowExecutionRepository: WorkflowExecutionRepository,
+    private readonly nodeEventPublisher: NodeEventPublisher,
+  ) {}
+
+  async enqueueActivation(args: ActivationEnqueueRequest): Promise<RunResult> {
+    const { result, queuedSnapshot } = await this.enqueueActivationWithSnapshot(args);
+    await this.nodeEventPublisher.publish("nodeQueued", queuedSnapshot);
+    return result;
+  }
+
+  async enqueueActivationWithSnapshot(
+    args: ActivationEnqueueRequest,
+  ): Promise<{ result: RunResult; queuedSnapshot: NodeExecutionSnapshot }> {
+    const receipt = await this.activationScheduler.enqueue(args.request);
+    const inputsByPort = NodeInputsByPortFactory.fromRequest(args.request);
+    const itemsIn =
+      args.request.kind === "multi"
+        ? args.planner.sumItemsByPort(args.request.inputsByPort)
+        : args.request.input.length;
+    const enqueuedAt = new Date().toISOString();
+    const pending: PendingNodeExecution = {
+      runId: args.runId,
+      activationId: args.request.activationId,
+      workflowId: args.workflowId,
+      nodeId: args.request.nodeId,
+      itemsIn,
+      inputsByPort,
+      receiptId: receipt.receiptId,
+      queue: receipt.queue,
+      batchId: args.request.batchId,
+      enqueuedAt,
+    };
+    const queuedSnapshot = NodeExecutionSnapshotFactory.queued({
+      runId: args.runId,
+      workflowId: args.workflowId,
+      nodeId: args.request.nodeId,
+      activationId: args.request.activationId,
+      parent: args.parent,
+      queuedAt: enqueuedAt,
+      inputsByPort,
+    });
+
+    await this.workflowExecutionRepository.save({
+      runId: args.runId,
+      workflowId: args.workflowId,
+      startedAt: args.startedAt,
+      parent: args.parent,
+      executionOptions: args.executionOptions,
+      control: args.control,
+      workflowSnapshot: args.workflowSnapshot,
+      mutableState: args.mutableState,
+      policySnapshot: args.policySnapshot,
+      engineCounters: args.engineCounters,
+      connectionInvocations: args.connectionInvocations ? [...args.connectionInvocations] : [],
+      status: "pending",
+      pending,
+      queue: args.pendingQueue.map((entry) => ({ ...entry })),
+      outputsByNode: (args.request.ctx.data as ReturnType<RunDataFactory["create"]>).dump(),
+      nodeSnapshotsByNodeId: {
+        ...args.previousNodeSnapshotsByNodeId,
+        [args.request.nodeId]: queuedSnapshot,
+      },
+    });
+    this.notifyPendingStatePersisted(args.runId);
+    return {
+      result: { runId: args.runId, workflowId: args.workflowId, startedAt: args.startedAt, status: "pending", pending },
+      queuedSnapshot,
+    };
+  }
+
+  private notifyPendingStatePersisted(runId: RunId): void {
+    this.activationScheduler.notifyPendingStatePersisted?.(runId);
+  }
+}