@codemation/core 0.0.1

package/src/execution/NodeRunStateWriter.ts

@@ -0,0 +1,185 @@
+import type {
+  ConnectionInvocationAppendArgs,
+  ConnectionInvocationRecord,
+  NodeActivationId,
+  NodeExecutionSnapshot,
+  NodeExecutionStatePublisher,
+  NodeId,
+  NodeInputsByPort,
+  NodeOutputs,
+  ParentExecutionRef,
+  RunId,
+  WorkflowExecutionRepository,
+  WorkflowId,
+} from "../types";
+
+import { NodeInputsByPortFactory } from "./NodeInputsByPortFactory";
+import { NodeExecutionSnapshotFactory } from "./NodeExecutionSnapshotFactory";
+
+export class NodeRunStateWriter implements NodeExecutionStatePublisher {
+  private chain: Promise<void> = Promise.resolve();
+
+  constructor(
+    private readonly workflowExecutionRepository: WorkflowExecutionRepository,
+    private readonly runId: RunId,
+    private readonly workflowId: WorkflowId,
+    private readonly parent: ParentExecutionRef | undefined,
+    private readonly publishNodeEvent: (
+      kind: "nodeQueued" | "nodeStarted" | "nodeCompleted" | "nodeFailed",
+      snapshot: NodeExecutionSnapshot,
+    ) => Promise<void>,
+  ) {}
+
+  markQueued(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+  }): Promise<void> {
+    return this.enqueue(async () => {
+      const state = await this.loadState();
+      const previous = state.nodeSnapshotsByNodeId?.[args.nodeId];
+      const queuedAt = new Date().toISOString();
+      const snapshot = NodeExecutionSnapshotFactory.queued({
+        runId: this.runId,
+        workflowId: this.workflowId,
+        nodeId: args.nodeId,
+        activationId: args.activationId ?? previous?.activationId ?? `synthetic_${args.nodeId}`,
+        parent: this.parent,
+        queuedAt,
+        inputsByPort: args.inputsByPort ?? previous?.inputsByPort ?? NodeInputsByPortFactory.empty(),
+      });
+      await this.saveSnapshot(state, snapshot);
+      await this.publishNodeEvent("nodeQueued", snapshot);
+    });
+  }
+
+  markRunning(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+  }): Promise<void> {
+    return this.enqueue(async () => {
+      const state = await this.loadState();
+      const previous = state.nodeSnapshotsByNodeId?.[args.nodeId];
+      const startedAt = new Date().toISOString();
+      const snapshot = NodeExecutionSnapshotFactory.running({
+        previous,
+        runId: this.runId,
+        workflowId: this.workflowId,
+        nodeId: args.nodeId,
+        activationId: args.activationId ?? previous?.activationId ?? `synthetic_${args.nodeId}`,
+        parent: this.parent,
+        startedAt,
+        inputsByPort: args.inputsByPort ?? previous?.inputsByPort ?? NodeInputsByPortFactory.empty(),
+      });
+      await this.saveSnapshot(state, snapshot);
+      await this.publishNodeEvent("nodeStarted", snapshot);
+    });
+  }
+
+  markCompleted(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+    outputs?: NodeOutputs;
+  }): Promise<void> {
+    return this.enqueue(async () => {
+      const state = await this.loadState();
+      const previous = state.nodeSnapshotsByNodeId?.[args.nodeId];
+      const finishedAt = new Date().toISOString();
+      const snapshot = NodeExecutionSnapshotFactory.completed({
+        previous,
+        runId: this.runId,
+        workflowId: this.workflowId,
+        nodeId: args.nodeId,
+        activationId: args.activationId ?? previous?.activationId ?? `synthetic_${args.nodeId}`,
+        parent: this.parent,
+        finishedAt,
+        inputsByPort: args.inputsByPort ?? previous?.inputsByPort ?? NodeInputsByPortFactory.empty(),
+        outputs: args.outputs ?? previous?.outputs ?? {},
+      });
+      await this.saveSnapshot(state, snapshot);
+      await this.publishNodeEvent("nodeCompleted", snapshot);
+    });
+  }
+
+  markFailed(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+    error: Error;
+  }): Promise<void> {
+    return this.enqueue(async () => {
+      const state = await this.loadState();
+      const previous = state.nodeSnapshotsByNodeId?.[args.nodeId];
+      const finishedAt = new Date().toISOString();
+      const snapshot = NodeExecutionSnapshotFactory.failed({
+        previous,
+        runId: this.runId,
+        workflowId: this.workflowId,
+        nodeId: args.nodeId,
+        activationId: args.activationId ?? previous?.activationId ?? `synthetic_${args.nodeId}`,
+        parent: this.parent,
+        finishedAt,
+        inputsByPort: args.inputsByPort ?? previous?.inputsByPort ?? NodeInputsByPortFactory.empty(),
+        error: args.error,
+      });
+      await this.saveSnapshot(state, snapshot);
+      await this.publishNodeEvent("nodeFailed", snapshot);
+    });
+  }
+
+  appendConnectionInvocation(args: ConnectionInvocationAppendArgs): Promise<void> {
+    return this.enqueue(async () => {
+      const state = await this.loadState();
+      const updatedAt = new Date().toISOString();
+      const record: ConnectionInvocationRecord = {
+        invocationId: args.invocationId,
+        runId: this.runId,
+        workflowId: this.workflowId,
+        connectionNodeId: args.connectionNodeId,
+        parentAgentNodeId: args.parentAgentNodeId,
+        parentAgentActivationId: args.parentAgentActivationId,
+        status: args.status,
+        managedInput: args.managedInput,
+        managedOutput: args.managedOutput,
+        error: args.error,
+        queuedAt: args.queuedAt,
+        startedAt: args.startedAt,
+        finishedAt: args.finishedAt,
+        updatedAt,
+      };
+      await this.workflowExecutionRepository.save({
+        ...state,
+        connectionInvocations: [...(state.connectionInvocations ?? []), record],
+      });
+    });
+  }
+
+  private enqueue(work: () => Promise<void>): Promise<void> {
+    const next = this.chain.then(work);
+    this.chain = next.catch(() => undefined);
+    return next;
+  }
+
+  private async loadState(): Promise<NonNullable<Awaited<ReturnType<WorkflowExecutionRepository["load"]>>>> {
+    const state = await this.workflowExecutionRepository.load(this.runId);
+    if (!state) {
+      throw new Error(`Unknown runId: ${this.runId}`);
+    }
+    return state;
+  }
+
+  private async saveSnapshot(
+    state: NonNullable<Awaited<ReturnType<WorkflowExecutionRepository["load"]>>>,
+    snapshot: NodeExecutionSnapshot,
+  ): Promise<void> {
+    await this.workflowExecutionRepository.save({
+      ...state,
+      nodeSnapshotsByNodeId: {
+        ...(state.nodeSnapshotsByNodeId ?? {}),
+        [snapshot.nodeId]: snapshot,
+      },
+    });
+  }
+}

package/src/execution/NodeRunStateWriterFactory.ts

@@ -0,0 +1,29 @@
+import type {
+  NodeExecutionStatePublisher,
+  ParentExecutionRef,
+  RunId,
+  WorkflowExecutionRepository,
+  WorkflowId,
+} from "../types";
+
+import { NodeEventPublisher } from "../events/NodeEventPublisher";
+import { NodeRunStateWriter } from "./NodeRunStateWriter";
+
+export class NodeRunStateWriterFactory {
+  constructor(
+    private readonly workflowExecutionRepository: WorkflowExecutionRepository,
+    private readonly nodeEventPublisher: NodeEventPublisher,
+  ) {}
+
+  create(runId: RunId, workflowId: WorkflowId, parent: ParentExecutionRef | undefined): NodeExecutionStatePublisher {
+    return new NodeRunStateWriter(
+      this.workflowExecutionRepository,
+      runId,
+      workflowId,
+      parent,
+      async (kind, snapshot) => {
+        await this.nodeEventPublisher.publish(kind, snapshot);
+      },
+    );
+  }
+}

package/src/execution/PersistedRunStateTerminalBuilder.ts

@@ -0,0 +1,25 @@
+import type { EngineRunCounters, PersistedRunState, RunQueueEntry } from "../types";
+
+/**
+ * Merges common terminal-run fields onto a loaded {@link PersistedRunState} without repeating object literals.
+ */
+export class PersistedRunStateTerminalBuilder {
+  mergeTerminal(args: {
+    state: PersistedRunState;
+    engineCounters: EngineRunCounters;
+    status: "completed" | "failed";
+    queue: RunQueueEntry[];
+    outputsByNode: PersistedRunState["outputsByNode"];
+    nodeSnapshotsByNodeId: NonNullable<PersistedRunState["nodeSnapshotsByNodeId"]>;
+  }): PersistedRunState {
+    return {
+      ...args.state,
+      engineCounters: args.engineCounters,
+      status: args.status,
+      pending: undefined,
+      queue: args.queue,
+      outputsByNode: args.outputsByNode,
+      nodeSnapshotsByNodeId: args.nodeSnapshotsByNodeId,
+    };
+  }
+}

package/src/execution/RunStateSemantics.ts

@@ -0,0 +1,158 @@
+import type {
+  Items,
+  NodeActivationId,
+  NodeExecutionSnapshot,
+  NodeId,
+  NodeInputsByPort,
+  NodeOutputs,
+  ParentExecutionRef,
+  PersistedRunControlState,
+  RunCurrentState,
+  RunDataFactory,
+  RunId,
+  RunQueueEntry,
+  WorkflowExecutionRepository,
+  WorkflowDefinition,
+  WorkflowId,
+} from "../types";
+
+import { WorkflowExecutableNodeClassifierFactory } from "../workflow/definition/WorkflowExecutableNodeClassifierFactory";
+import { RunQueuePlanner } from "../planning/RunQueuePlanner";
+
+import { MissingRuntimeExecutionMarker } from "../workflowSnapshots/MissingRuntimeExecutionMarker";
+import { NodeExecutionSnapshotFactory } from "./NodeExecutionSnapshotFactory";
+import { NodeInputsByPortFactory } from "./NodeInputsByPortFactory";
+
+export class RunStateSemantics {
+  constructor(private readonly missingRuntimeExecutionMarker: MissingRuntimeExecutionMarker) {}
+
+  isStopConditionSatisfied(stopCondition: PersistedRunControlState["stopCondition"], nodeId: NodeId): boolean {
+    if (!stopCondition || stopCondition.kind === "workflowCompleted") {
+      return false;
+    }
+    return stopCondition.nodeId === nodeId;
+  }
+
+  resolveResultOutputs(
+    workflow: WorkflowDefinition,
+    stopCondition: PersistedRunControlState["stopCondition"],
+    outputsByNode: Record<NodeId, NodeOutputs>,
+  ): Items {
+    if (stopCondition?.kind === "nodeCompleted") {
+      return outputsByNode[stopCondition.nodeId]?.main ?? [];
+    }
+    const lastNodeId =
+      WorkflowExecutableNodeClassifierFactory.create(workflow).lastExecutableNodeIdInDefinitionOrder(workflow);
+    return outputsByNode[lastNodeId]?.main ?? [];
+  }
+
+  applySkippedSnapshots(args: {
+    runId: RunId;
+    workflowId: WorkflowId;
+    parent?: ParentExecutionRef;
+    currentState: RunCurrentState;
+    skippedNodeIds: ReadonlyArray<NodeId>;
+    preservedPinnedNodeIds: ReadonlyArray<NodeId>;
+    finishedAt: string;
+  }): Record<NodeId, NodeExecutionSnapshot> {
+    const snapshots = { ...args.currentState.nodeSnapshotsByNodeId };
+    const skippedPinnedNodeIds = new Set<NodeId>(
+      args.preservedPinnedNodeIds.filter((nodeId) => args.skippedNodeIds.includes(nodeId)),
+    );
+    for (const nodeId of args.skippedNodeIds) {
+      if (args.currentState.mutableState?.nodesById?.[nodeId]?.pinnedOutputsByPort) {
+        skippedPinnedNodeIds.add(nodeId);
+      }
+    }
+    for (const nodeId of skippedPinnedNodeIds) {
+      const previous = snapshots[nodeId];
+      snapshots[nodeId] = NodeExecutionSnapshotFactory.completed({
+        previous,
+        runId: args.runId,
+        workflowId: args.workflowId,
+        nodeId,
+        activationId: previous?.activationId ?? `synthetic_${nodeId}`,
+        parent: args.parent,
+        finishedAt: args.finishedAt,
+        inputsByPort: previous?.inputsByPort ?? NodeInputsByPortFactory.empty(),
+        outputs: args.currentState.outputsByNode[nodeId] ?? {},
+        fromPinnedOutput: true,
+      });
+    }
+    return snapshots;
+  }
+
+  applyPinnedQueueSkips(args: {
+    runId: RunId;
+    workflowId: WorkflowId;
+    parent?: ParentExecutionRef;
+    mutableState: NonNullable<Awaited<ReturnType<WorkflowExecutionRepository["load"]>>>["mutableState"];
+    planner: RunQueuePlanner;
+    queue: RunQueueEntry[];
+    data: ReturnType<RunDataFactory["create"]>;
+    nodeSnapshotsByNodeId: Record<NodeId, NodeExecutionSnapshot>;
+    finishedAt: string;
+  }): void {
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (let index = 0; index < args.queue.length; index += 1) {
+        const queueEntry = args.queue[index]!;
+        const pinnedOutputs = args.mutableState?.nodesById?.[queueEntry.nodeId]?.pinnedOutputsByPort;
+        if (!pinnedOutputs) {
+          continue;
+        }
+        args.queue.splice(index, 1);
+        const previous = args.nodeSnapshotsByNodeId[queueEntry.nodeId];
+        args.nodeSnapshotsByNodeId[queueEntry.nodeId] = NodeExecutionSnapshotFactory.completed({
+          previous,
+          runId: args.runId,
+          workflowId: args.workflowId,
+          nodeId: queueEntry.nodeId,
+          activationId: previous?.activationId ?? `synthetic_${queueEntry.nodeId}`,
+          parent: args.parent,
+          finishedAt: args.finishedAt,
+          inputsByPort: this.resolveQueueEntryInputsByPort(queueEntry),
+          outputs: pinnedOutputs,
+          fromPinnedOutput: true,
+        });
+        args.data.setOutputs(queueEntry.nodeId, pinnedOutputs);
+        args.planner.applyOutputs(args.queue, {
+          fromNodeId: queueEntry.nodeId,
+          outputs: pinnedOutputs as any,
+          batchId: queueEntry.batchId ?? "batch_1",
+        });
+        changed = true;
+        break;
+      }
+    }
+  }
+
+  createFinishedSnapshot(args: {
+    workflow: WorkflowDefinition;
+    previous?: NodeExecutionSnapshot;
+    runId: RunId;
+    workflowId: WorkflowId;
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+    parent?: ParentExecutionRef;
+    finishedAt: string;
+    inputsByPort: NodeInputsByPort;
+    outputs: NodeOutputs;
+  }): NodeExecutionSnapshot {
+    const definition = args.workflow.nodes.find((node) => node.id === args.nodeId);
+    if (this.missingRuntimeExecutionMarker.isMarked(definition?.config)) {
+      return NodeExecutionSnapshotFactory.skipped(args);
+    }
+    return NodeExecutionSnapshotFactory.completed(args);
+  }
+
+  private resolveQueueEntryInputsByPort(queueEntry: RunQueueEntry): NodeInputsByPort {
+    if (queueEntry.collect) {
+      return queueEntry.collect.received;
+    }
+    return {
+      [queueEntry.toInput ?? "in"]: queueEntry.input,
+    };
+  }
+}

package/src/execution/WorkflowRunExecutionContextFactory.ts

@@ -0,0 +1,45 @@
+import type {
+  ExecutionContextFactory,
+  NodeExecutionStatePublisher,
+  NodeId,
+  ParentExecutionRef,
+  RunDataFactory,
+  RunId,
+  WorkflowId,
+} from "../types";
+
+import { CredentialResolverFactory } from "./CredentialResolverFactory";
+
+/**
+ * Shared {@link ExecutionContextFactory#create} wiring for workflow runners (base context before node-specific fields).
+ */
+export class WorkflowRunExecutionContextFactory {
+  constructor(
+    private readonly executionContextFactory: ExecutionContextFactory,
+    private readonly credentialResolverFactory: CredentialResolverFactory,
+  ) {}
+
+  create(args: {
+    runId: RunId;
+    workflowId: WorkflowId;
+    nodeId: NodeId;
+    parent?: ParentExecutionRef;
+    subworkflowDepth: number;
+    engineMaxNodeActivations: number;
+    engineMaxSubworkflowDepth: number;
+    data: ReturnType<RunDataFactory["create"]>;
+    nodeState?: NodeExecutionStatePublisher;
+  }) {
+    return this.executionContextFactory.create({
+      runId: args.runId,
+      workflowId: args.workflowId,
+      parent: args.parent,
+      subworkflowDepth: args.subworkflowDepth,
+      engineMaxNodeActivations: args.engineMaxNodeActivations,
+      engineMaxSubworkflowDepth: args.engineMaxSubworkflowDepth,
+      data: args.data,
+      nodeState: args.nodeState,
+      getCredential: this.credentialResolverFactory.create(args.workflowId, args.nodeId),
+    });
+  }
+}

package/src/execution/asyncSleeper.types.ts

@@ -0,0 +1,3 @@
+export interface AsyncSleeper {
+  sleep(ms: number): Promise<void>;
+}

package/src/execution/index.ts

@@ -0,0 +1,26 @@
+export { ActivationEnqueueService } from "./ActivationEnqueueService";
+export { CredentialResolverFactory } from "./CredentialResolverFactory";
+export { DefaultAsyncSleeper } from "./DefaultAsyncSleeper";
+export { DefaultExecutionContextFactory } from "./DefaultExecutionContextFactory";
+export { InProcessRetryRunner } from "./InProcessRetryRunner";
+export { InProcessRetryRunnerFactory } from "./InProcessRetryRunnerFactory";
+export { NodeActivationRequestComposer } from "./NodeActivationRequestComposer";
+export { NodeExecutionSnapshotFactory } from "./NodeExecutionSnapshotFactory";
+export { NodeExecutor } from "./NodeExecutor";
+export { NodeExecutorFactory } from "./NodeExecutorFactory";
+export { NodeInstanceFactory } from "./NodeInstanceFactory";
+export { NodeInstanceFactoryFactory } from "./NodeInstanceFactoryFactory";
+export { NodeInputsByPortFactory } from "./NodeInputsByPortFactory";
+export { NodeRunStateWriter } from "./NodeRunStateWriter";
+export { NodeRunStateWriterFactory } from "./NodeRunStateWriterFactory";
+export { PersistedRunStateTerminalBuilder } from "./PersistedRunStateTerminalBuilder";
+export { RunStateSemantics } from "./RunStateSemantics";
+export { WorkflowRunExecutionContextFactory } from "./WorkflowRunExecutionContextFactory";
+export type { AsyncSleeper } from "./asyncSleeper.types";
+export { RunContinuationService } from "../orchestration/RunContinuationService";
+export { RunStartService } from "../orchestration/RunStartService";
+export { ConfigDrivenOffloadPolicy } from "../scheduler/ConfigDrivenOffloadPolicy";
+export { DefaultDrivingScheduler } from "../scheduler/DefaultDrivingScheduler";
+export { HintOnlyOffloadPolicy } from "../scheduler/HintOnlyOffloadPolicy";
+export { InlineDrivingScheduler } from "../scheduler/InlineDrivingScheduler";
+export { LocalOnlyScheduler } from "../scheduler/LocalOnlyScheduler";

package/src/index.ts

@@ -0,0 +1,18 @@
+export { SystemClock, type Clock } from "./contracts/Clock";
+export * from "./ai/AiHost";
+export * from "./workflow";
+export * from "./di";
+export * from "./events";
+export * from "./runtime-types/runtimeTypeDecorators.types";
+export * from "./serialization/ItemsInputNormalizer";
+export { DefaultExecutionBinaryService, UnavailableBinaryStorage } from "./binaries";
+export {
+  CredentialResolverFactory,
+  DefaultAsyncSleeper,
+  DefaultExecutionContextFactory,
+  InProcessRetryRunner,
+} from "./execution";
+export { EngineExecutionLimitsPolicy, type EngineExecutionLimitsPolicyConfig } from "./policies";
+export { InMemoryBinaryStorage, InMemoryRunDataFactory } from "./runStorage";
+export { InMemoryLiveWorkflowRepository, RunIntentService } from "./runtime";
+export * from "./types";