@codemation/core 0.0.1

package/src/runStorage/BinaryBodyBufferReader.ts

@@ -0,0 +1,57 @@
+import { ReadableStream } from "node:stream/web";
+
+import type { BinaryBody } from "../types";
+
+export class BinaryBodyBufferReader {
+  async read(body: BinaryBody): Promise<Uint8Array> {
+    if (body instanceof Uint8Array) {
+      return body;
+    }
+    if (body instanceof ArrayBuffer) {
+      return new Uint8Array(body);
+    }
+    if (body instanceof ReadableStream) {
+      return await this.readReadableStream(body);
+    }
+    return await this.readAsyncIterable(body);
+  }
+
+  private async readReadableStream(body: ReadableStream<Uint8Array>): Promise<Uint8Array> {
+    const reader = body.getReader();
+    const chunks: Uint8Array[] = [];
+    let totalSize = 0;
+    try {
+      while (true) {
+        const result = await reader.read();
+        if (result.done) {
+          break;
+        }
+        chunks.push(result.value);
+        totalSize += result.value.byteLength;
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    return this.joinChunks(chunks, totalSize);
+  }
+
+  private async readAsyncIterable(body: AsyncIterable<Uint8Array>): Promise<Uint8Array> {
+    const chunks: Uint8Array[] = [];
+    let totalSize = 0;
+    for await (const chunk of body) {
+      chunks.push(chunk);
+      totalSize += chunk.byteLength;
+    }
+    return this.joinChunks(chunks, totalSize);
+  }
+
+  private joinChunks(chunks: ReadonlyArray<Uint8Array>, totalSize: number): Uint8Array {
+    const bytes = new Uint8Array(totalSize);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return bytes;
+  }
+}

package/src/runStorage/BinaryBodyReadableStreamFactory.ts

@@ -0,0 +1,21 @@
+import { ReadableStream } from "node:stream/web";
+
+export class BinaryBodyReadableStreamFactory {
+  constructor(private readonly bytes: Uint8Array) {}
+
+  create(): ReadableStream<Uint8Array> {
+    const value = this.bytes;
+    let consumed = false;
+    return new ReadableStream<Uint8Array>({
+      pull(controller) {
+        if (consumed) {
+          controller.close();
+          return;
+        }
+        consumed = true;
+        controller.enqueue(value);
+        controller.close();
+      },
+    });
+  }
+}

package/src/runStorage/InMemoryBinaryStorageRegistry.ts

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+
+import type {
+  BinaryBody,
+  BinaryStorage,
+  BinaryStorageReadResult,
+  BinaryStorageStatResult,
+  BinaryStorageWriteResult,
+} from "../types";
+
+import { BinaryBodyBufferReader } from "./BinaryBodyBufferReader";
+import { BinaryBodyReadableStreamFactory } from "./BinaryBodyReadableStreamFactory";
+
+export class InMemoryBinaryStorage implements BinaryStorage {
+  readonly driverName = "memory";
+  private readonly values = new Map<string, Uint8Array>();
+
+  async write(args: { storageKey: string; body: BinaryBody }): Promise<BinaryStorageWriteResult> {
+    const bytes = await new BinaryBodyBufferReader().read(args.body);
+    this.values.set(args.storageKey, bytes);
+    return {
+      storageKey: args.storageKey,
+      size: bytes.byteLength,
+      sha256: createHash("sha256").update(bytes).digest("hex"),
+    };
+  }
+
+  async openReadStream(storageKey: string): Promise<BinaryStorageReadResult | undefined> {
+    const bytes = this.values.get(storageKey);
+    if (!bytes) {
+      return undefined;
+    }
+    return {
+      body: new BinaryBodyReadableStreamFactory(bytes).create(),
+      size: bytes.byteLength,
+    };
+  }
+
+  async stat(storageKey: string): Promise<BinaryStorageStatResult> {
+    const bytes = this.values.get(storageKey);
+    if (!bytes) {
+      return { exists: false };
+    }
+    return { exists: true, size: bytes.byteLength };
+  }
+
+  async delete(storageKey: string): Promise<void> {
+    this.values.delete(storageKey);
+  }
+}
+
+export { BinaryBodyBufferReader } from "./BinaryBodyBufferReader";
+export { BinaryBodyReadableStreamFactory } from "./BinaryBodyReadableStreamFactory";

package/src/runStorage/InMemoryRunData.ts

@@ -0,0 +1,33 @@
+import type { Items, MutableRunData, NodeId, NodeOutputs, OutputPortKey } from "../types";
+
+export class InMemoryRunData implements MutableRunData {
+  private readonly byNode = new Map<NodeId, NodeOutputs>();
+
+  constructor(initial?: Record<NodeId, NodeOutputs>) {
+    if (initial) {
+      for (const [nodeId, outputs] of Object.entries(initial)) this.byNode.set(nodeId, outputs);
+    }
+  }
+
+  setOutputs(nodeId: NodeId, outputs: NodeOutputs): void {
+    this.byNode.set(nodeId, outputs);
+  }
+
+  getOutputs(nodeId: NodeId): NodeOutputs | undefined {
+    return this.byNode.get(nodeId);
+  }
+
+  getOutputItems(nodeId: NodeId, output: OutputPortKey = "main"): Items {
+    return this.byNode.get(nodeId)?.[output] ?? [];
+  }
+
+  getOutputItem(nodeId: NodeId, itemIndex: number, output: OutputPortKey = "main") {
+    return this.getOutputItems(nodeId, output)[itemIndex];
+  }
+
+  dump(): Record<NodeId, NodeOutputs> {
+    const out: Record<NodeId, NodeOutputs> = {};
+    for (const [nodeId, outputs] of this.byNode.entries()) out[nodeId] = outputs;
+    return out;
+  }
+}

package/src/runStorage/InMemoryRunDataFactory.ts

@@ -0,0 +1,8 @@
+import type { MutableRunData, NodeId, NodeOutputs, RunDataFactory } from "../types";
+import { InMemoryRunData } from "./InMemoryRunData";
+
+export class InMemoryRunDataFactory implements RunDataFactory {
+  create(initial?: Record<NodeId, NodeOutputs>): MutableRunData {
+    return new InMemoryRunData(initial);
+  }
+}

package/src/runStorage/InMemoryWorkflowExecutionRepository.ts

@@ -0,0 +1,95 @@
+import type {
+  EngineRunCounters,
+  NodeId,
+  NodeOutputs,
+  ParentExecutionRef,
+  PersistedRunState,
+  RunId,
+  RunSummary,
+  WorkflowExecutionListingRepository,
+  WorkflowExecutionPruneRepository,
+  WorkflowExecutionRepository,
+  RunPruneCandidate,
+  WorkflowId,
+} from "../types";
+import { RunFinishedAtFactory } from "../contracts/runFinishedAtFactory";
+import { RunSummaryMapper } from "./RunSummaryMapper";
+
+export class InMemoryWorkflowExecutionRepository
+  implements WorkflowExecutionRepository, WorkflowExecutionListingRepository, WorkflowExecutionPruneRepository
+{
+  private readonly runs = new Map<RunId, PersistedRunState>();
+
+  async createRun(args: {
+    runId: RunId;
+    workflowId: WorkflowId;
+    startedAt: string;
+    parent?: ParentExecutionRef;
+    executionOptions?: PersistedRunState["executionOptions"];
+    control?: PersistedRunState["control"];
+    workflowSnapshot?: PersistedRunState["workflowSnapshot"];
+    mutableState?: PersistedRunState["mutableState"];
+    policySnapshot?: PersistedRunState["policySnapshot"];
+    engineCounters?: EngineRunCounters;
+  }): Promise<void> {
+    this.runs.set(args.runId, {
+      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,
+      status: "running",
+      queue: [],
+      outputsByNode: {} as Record<NodeId, NodeOutputs>,
+      nodeSnapshotsByNodeId: {},
+      connectionInvocations: [],
+    });
+  }
+
+  async load(runId: RunId): Promise<PersistedRunState | undefined> {
+    return this.runs.get(runId);
+  }
+
+  async save(state: PersistedRunState): Promise<void> {
+    this.runs.set(state.runId, state);
+  }
+
+  async deleteRun(runId: RunId): Promise<void> {
+    this.runs.delete(runId);
+  }
+
+  async listRuns(args?: Readonly<{ workflowId?: WorkflowId; limit?: number }>): Promise<ReadonlyArray<RunSummary>> {
+    const limit = args?.limit ?? 50;
+    const summaries = [...this.runs.values()]
+      .filter((s) => (args?.workflowId ? s.workflowId === args.workflowId : true))
+      .sort((a, b) => b.startedAt.localeCompare(a.startedAt))
+      .slice(0, limit)
+      .map((s) => RunSummaryMapper.fromPersistedState(s));
+    return summaries;
+  }
+
+  async listRunsOlderThan(
+    args: Readonly<{ beforeIso: string; limit?: number }>,
+  ): Promise<ReadonlyArray<RunPruneCandidate>> {
+    const limit = args.limit ?? 100;
+    const out: RunPruneCandidate[] = [];
+    for (const s of this.runs.values()) {
+      if (s.status !== "completed" && s.status !== "failed") continue;
+      const finishedAt = RunFinishedAtFactory.resolveIso(s);
+      if (!finishedAt || finishedAt >= args.beforeIso) continue;
+      out.push({
+        runId: s.runId,
+        workflowId: s.workflowId,
+        startedAt: s.startedAt,
+        finishedAt,
+      });
+    }
+    out.sort((a, b) => a.finishedAt.localeCompare(b.finishedAt));
+    return out.slice(0, limit);
+  }
+}

package/src/runStorage/RunSummaryMapper.ts

@@ -0,0 +1,17 @@
+import { RunFinishedAtFactory } from "../contracts/runFinishedAtFactory";
+import type { PersistedRunState, RunSummary } from "../types";
+
+/** Maps persisted run state to API run summaries for listings. */
+export class RunSummaryMapper {
+  static fromPersistedState(state: PersistedRunState): RunSummary {
+    return {
+      runId: state.runId,
+      workflowId: state.workflowId,
+      startedAt: state.startedAt,
+      status: state.status,
+      finishedAt: RunFinishedAtFactory.resolveIso(state),
+      parent: state.parent,
+      executionOptions: state.executionOptions,
+    };
+  }
+}

package/src/runStorage/index.ts

@@ -0,0 +1,7 @@
+export { BinaryBodyBufferReader } from "./BinaryBodyBufferReader";
+export { BinaryBodyReadableStreamFactory } from "./BinaryBodyReadableStreamFactory";
+export { InMemoryBinaryStorage } from "./InMemoryBinaryStorageRegistry";
+export { InMemoryRunData } from "./InMemoryRunData";
+export { InMemoryRunDataFactory } from "./InMemoryRunDataFactory";
+export { InMemoryWorkflowExecutionRepository } from "./InMemoryWorkflowExecutionRepository";
+export { RunSummaryMapper } from "./RunSummaryMapper";

package/src/runtime/EngineFactory.ts

@@ -0,0 +1,151 @@
+import type { EngineDeps } from "../types";
+
+import { MissingRuntimeFallbacks } from "../workflowSnapshots/MissingRuntimeFallbacksFactory";
+import { MissingRuntimeExecutionMarker } from "../workflowSnapshots/MissingRuntimeExecutionMarker";
+import { WorkflowSnapshotCodec } from "../workflowSnapshots/WorkflowSnapshotCodec";
+import { WorkflowSnapshotResolver } from "../workflowSnapshots/WorkflowSnapshotResolver";
+import { ActivationEnqueueService } from "../execution/ActivationEnqueueService";
+import { NodeActivationRequestComposer } from "../execution/NodeActivationRequestComposer";
+import { PersistedRunStateTerminalBuilder } from "../execution/PersistedRunStateTerminalBuilder";
+import { RunContinuationService } from "../orchestration/RunContinuationService";
+import { RunStartService } from "../orchestration/RunStartService";
+import { RunStateSemantics } from "../execution/RunStateSemantics";
+import { WorkflowRunExecutionContextFactory } from "../execution/WorkflowRunExecutionContextFactory";
+import { RunTerminalPersistenceCoordinator } from "../policies/storage/RunTerminalPersistenceCoordinator";
+import { WorkflowPolicyErrorServices } from "../policies/WorkflowPolicyErrorServices";
+import { WorkflowStoragePolicyEvaluator } from "../policies/storage/WorkflowStoragePolicyEvaluator";
+import { NodeEventPublisher } from "../events/NodeEventPublisher";
+import { EngineExecutionLimitsPolicy } from "../policies/executionLimits/EngineExecutionLimitsPolicy";
+import { EngineWorkflowPlanningFactory } from "../planning/EngineWorkflowPlanningFactory";
+import { TriggerRuntimeService } from "../orchestration/TriggerRuntimeService";
+import { EngineWaiters } from "../orchestration/EngineWaiters";
+import { Engine } from "../orchestration/Engine";
+import { CredentialResolverFactory } from "../execution/CredentialResolverFactory";
+import { NodeRunStateWriterFactory } from "../execution/NodeRunStateWriterFactory";
+
+/**
+ * {@link EngineDeps} plus optional overrides for workflow-snapshot materialization.
+ * Overrides keep default construction in this factory while allowing tests or advanced wiring to inject instances.
+ */
+export type EngineCompositionDeps = EngineDeps & {
+  workflowSnapshotCodec?: WorkflowSnapshotCodec;
+  missingRuntimeFallbacks?: MissingRuntimeFallbacks;
+  /** When set, used for run-start, trigger, and continuation limit defaults. */
+  executionLimitsPolicy?: EngineExecutionLimitsPolicy;
+};
+
+/**
+ * Composes the {@link Engine} graph from {@link EngineCompositionDeps}. Production wiring usually goes through
+ * {@link import("../bootstrap/runtime/EngineRuntimeRegistrar").EngineRuntimeRegistrar}; this factory remains for tests and custom composition.
+ * Exported from `@codemation/core/bootstrap` (not the main `@codemation/core` barrel).
+ */
+export class EngineFactory {
+  create(deps: EngineCompositionDeps): Engine {
+    const waiters = new EngineWaiters();
+    const credentialResolverFactory = new CredentialResolverFactory(deps.credentialSessions);
+    const nodeEventPublisher = new NodeEventPublisher(deps.eventBus);
+    const nodeStatePublisherFactory = new NodeRunStateWriterFactory(
+      deps.workflowExecutionRepository,
+      nodeEventPublisher,
+    );
+    const planningFactory = new EngineWorkflowPlanningFactory(deps.workflowNodeInstanceFactory);
+    const executionLimitsPolicy = deps.executionLimitsPolicy ?? new EngineExecutionLimitsPolicy();
+    const workflowSnapshotCodec = deps.workflowSnapshotCodec ?? new WorkflowSnapshotCodec(deps.tokenRegistry);
+    const missingRuntimeFallbacks = deps.missingRuntimeFallbacks ?? new MissingRuntimeFallbacks();
+    const workflowSnapshotResolver = new WorkflowSnapshotResolver(
+      deps.workflowRepository,
+      deps.tokenRegistry,
+      workflowSnapshotCodec,
+      missingRuntimeFallbacks,
+    );
+
+    const semantics = new RunStateSemantics(new MissingRuntimeExecutionMarker());
+    const activationEnqueueService = new ActivationEnqueueService(
+      deps.activationScheduler,
+      deps.workflowExecutionRepository,
+      nodeEventPublisher,
+    );
+    const runExecutionContextFactory = new WorkflowRunExecutionContextFactory(
+      deps.executionContextFactory,
+      credentialResolverFactory,
+    );
+    const nodeActivationRequestComposer = new NodeActivationRequestComposer(
+      deps.activationIdFactory,
+      credentialResolverFactory,
+    );
+    const persistedRunStateTerminalBuilder = new PersistedRunStateTerminalBuilder();
+    const storagePolicyEvaluator = new WorkflowStoragePolicyEvaluator(deps.nodeResolver);
+    const terminalPersistence = new RunTerminalPersistenceCoordinator(
+      deps.workflowExecutionRepository,
+      storagePolicyEvaluator,
+    );
+    const policyErrorServices = new WorkflowPolicyErrorServices(deps.nodeResolver);
+
+    const runStartService = new RunStartService(
+      deps.runIdFactory,
+      deps.workflowExecutionRepository,
+      deps.runDataFactory,
+      workflowSnapshotCodec,
+      planningFactory,
+      nodeStatePublisherFactory,
+      runExecutionContextFactory,
+      nodeActivationRequestComposer,
+      activationEnqueueService,
+      semantics,
+      waiters,
+      deps.workflowPolicyRuntimeDefaults,
+      executionLimitsPolicy,
+    );
+    const runContinuationService = new RunContinuationService(
+      deps.activationIdFactory,
+      deps.workflowExecutionRepository,
+      deps.runDataFactory,
+      runExecutionContextFactory,
+      workflowSnapshotResolver,
+      planningFactory,
+      nodeStatePublisherFactory,
+      credentialResolverFactory,
+      nodeActivationRequestComposer,
+      persistedRunStateTerminalBuilder,
+      activationEnqueueService,
+      nodeEventPublisher,
+      semantics,
+      waiters,
+      policyErrorServices,
+      terminalPersistence,
+      executionLimitsPolicy,
+    );
+
+    const triggerRuntime = new TriggerRuntimeService(
+      deps.workflowRepository,
+      deps.workflowActivationPolicy,
+      deps.runIdFactory,
+      deps.runDataFactory,
+      deps.executionContextFactory,
+      credentialResolverFactory,
+      nodeStatePublisherFactory,
+      deps.nodeResolver,
+      deps.triggerSetupStateRepository,
+      {
+        emit: async (workflow, triggerNodeId, items) => {
+          await runStartService.runWorkflow(workflow, triggerNodeId, items, undefined);
+        },
+      },
+      executionLimitsPolicy,
+      deps.triggerRuntimeDiagnostics,
+    );
+
+    const engine = new Engine({
+      liveWorkflowRepository: deps.liveWorkflowRepository,
+      tokenRegistry: deps.tokenRegistry,
+      webhookTriggerMatcher: deps.webhookTriggerMatcher,
+      workflowSnapshotResolver,
+      triggerRuntime,
+      runStartService,
+      runContinuationService,
+    });
+
+    deps.activationScheduler.setContinuation?.(engine);
+    return engine;
+  }
+}

package/src/runtime/EngineWorkflowRunnerService.ts

@@ -0,0 +1,39 @@
+import type {
+  Items,
+  NodeId,
+  ParentExecutionRef,
+  RunResult,
+  WorkflowDefinition,
+  WorkflowId,
+  WorkflowRepository,
+} from "../types";
+import { WorkflowExecutableNodeClassifierFactory } from "../workflow";
+
+import { Engine } from "../orchestration/Engine";
+
+export class EngineWorkflowRunnerService {
+  constructor(
+    private readonly engine: Engine,
+    private readonly workflowRepository: WorkflowRepository,
+  ) {}
+
+  async runById(args: {
+    workflowId: WorkflowId;
+    startAt?: NodeId;
+    items: Items;
+    parent?: ParentExecutionRef;
+  }): Promise<RunResult> {
+    const { workflowId, startAt, items, parent } = args;
+    const wf = this.workflowRepository.get(workflowId);
+    if (!wf) throw new Error(`Unknown workflowId: ${workflowId}`);
+
+    const startNodeId = startAt ?? this.findDefaultStartNodeId(wf);
+    const scheduled = await this.engine.runWorkflow(wf, startNodeId, items, parent);
+    if (scheduled.status !== "pending") return scheduled;
+    return await this.engine.waitForCompletion(scheduled.runId);
+  }
+
+  private findDefaultStartNodeId(wf: WorkflowDefinition): NodeId {
+    return WorkflowExecutableNodeClassifierFactory.create(wf).findDefaultExecutableStartNodeId(wf);
+  }
+}

package/src/runtime/EngineWorkflowRunnerServiceFactory.ts

@@ -0,0 +1,11 @@
+import type { WorkflowRepository } from "../types";
+
+import { Engine } from "../orchestration/Engine";
+
+import { EngineWorkflowRunnerService } from "./EngineWorkflowRunnerService";
+
+export class EngineWorkflowRunnerServiceFactory {
+  create(engine: Engine, workflowRepository: WorkflowRepository): EngineWorkflowRunnerService {
+    return new EngineWorkflowRunnerService(engine, workflowRepository);
+  }
+}

package/src/runtime/InMemoryLiveWorkflowRepository.ts

@@ -0,0 +1,20 @@
+import type { LiveWorkflowRepository, WorkflowDefinition, WorkflowId } from "../types";
+
+export class InMemoryLiveWorkflowRepository implements LiveWorkflowRepository {
+  private readonly workflowsById = new Map<WorkflowId, WorkflowDefinition>();
+
+  setWorkflows(workflows: ReadonlyArray<WorkflowDefinition>): void {
+    this.workflowsById.clear();
+    for (const workflow of workflows) {
+      this.workflowsById.set(workflow.id, workflow);
+    }
+  }
+
+  list(): ReadonlyArray<WorkflowDefinition> {
+    return [...this.workflowsById.values()];
+  }
+
+  get(workflowId: WorkflowId): WorkflowDefinition | undefined {
+    return this.workflowsById.get(workflowId);
+  }
+}