@codemation/core 0.0.1

package/src/planning/EngineWorkflowPlanningFactory.ts

@@ -0,0 +1,63 @@
+import type { WorkflowDefinition, WorkflowNodeInstanceFactory } from "../types";
+import { WorkflowExecutableNodeClassifierFactory } from "../workflow/definition/WorkflowExecutableNodeClassifierFactory";
+
+import { RunQueuePlanner } from "./RunQueuePlanner";
+import { WorkflowTopology } from "./WorkflowTopologyPlanner";
+
+export class EngineWorkflowPlanningFactory {
+  constructor(private readonly workflowNodeInstanceFactory: WorkflowNodeInstanceFactory) {}
+
+  create(workflow: WorkflowDefinition): Readonly<{ topology: WorkflowTopology; planner: RunQueuePlanner }> {
+    this.validateAcyclic(workflow);
+    const topology = WorkflowTopology.fromWorkflow(workflow);
+    const nodeInstances = this.workflowNodeInstanceFactory.createNodes(workflow);
+    const planner = new RunQueuePlanner(topology, nodeInstances);
+    planner.validateNodeKinds();
+    return { topology, planner };
+  }
+
+  private validateAcyclic(workflow: WorkflowDefinition): void {
+    const classifier = WorkflowExecutableNodeClassifierFactory.create(workflow);
+    const outgoing = new Map<string, string[]>();
+    const visitState = new Map<string, "unvisited" | "visiting" | "done">();
+
+    for (const node of workflow.nodes) {
+      if (classifier.isExecutableNodeId(node.id)) {
+        visitState.set(node.id, "unvisited");
+      }
+    }
+
+    for (const edge of workflow.edges) {
+      if (!classifier.isExecutableNodeId(edge.from.nodeId) || !classifier.isExecutableNodeId(edge.to.nodeId)) {
+        continue;
+      }
+      const destinations = outgoing.get(edge.from.nodeId) ?? [];
+      destinations.push(edge.to.nodeId);
+      outgoing.set(edge.from.nodeId, destinations);
+    }
+
+    for (const node of workflow.nodes) {
+      if (classifier.isExecutableNodeId(node.id) && visitState.get(node.id) === "unvisited") {
+        this.depthFirstSearch(node.id, outgoing, visitState);
+      }
+    }
+  }
+
+  private depthFirstSearch(
+    nodeId: string,
+    outgoing: ReadonlyMap<string, ReadonlyArray<string>>,
+    visitState: Map<string, "unvisited" | "visiting" | "done">,
+  ): void {
+    visitState.set(nodeId, "visiting");
+    for (const toNodeId of outgoing.get(nodeId) ?? []) {
+      const state = visitState.get(toNodeId);
+      if (state === "visiting") {
+        throw new Error(`Workflow graph contains a directed cycle (edge ${nodeId} -> ${toNodeId}).`);
+      }
+      if (state === "unvisited") {
+        this.depthFirstSearch(toNodeId, outgoing, visitState);
+      }
+    }
+    visitState.set(nodeId, "done");
+  }
+}

package/src/planning/RunQueuePlanner.ts

@@ -0,0 +1,302 @@
+import type { InputPortKey, Items, NodeId, OutputPortKey, RunQueueEntry } from "../types";
+
+import { WorkflowTopology } from "./WorkflowTopologyPlanner";
+
+export type PlannedActivation =
+  | Readonly<{ kind: "single"; nodeId: NodeId; input: Items; batchId: string }>
+  | Readonly<{ kind: "multi"; nodeId: NodeId; inputsByPort: Readonly<Record<InputPortKey, Items>>; batchId: string }>;
+
+export class RunQueuePlanner {
+  constructor(
+    private readonly topology: WorkflowTopology,
+    private readonly nodeInstances: ReadonlyMap<NodeId, unknown>,
+  ) {}
+
+  validateNodeKinds(): void {
+    for (const [toNodeId, inputs] of this.topology.expectedInputsByNode.entries()) {
+      if (inputs.length <= 1) {
+        const only = inputs[0];
+        if (only && only !== "in") {
+          const inst = this.nodeInstances.get(toNodeId);
+          if (!this.isMultiInputNode(inst))
+            throw new Error(`Node ${toNodeId} only supports input 'in' (got '${only}').`);
+        }
+        continue;
+      }
+
+      const inst = this.nodeInstances.get(toNodeId);
+      if (!this.isMultiInputNode(inst)) {
+        throw new Error(
+          `Node ${toNodeId} has ${inputs.length} inbound edges. Insert a Merge node to combine branches.`,
+        );
+      }
+    }
+  }
+
+  seedFromTrigger(args: { startNodeId: NodeId; items: Items; batchId: string }): RunQueueEntry[] {
+    const queue: RunQueueEntry[] = [];
+    for (const e of this.topology.outgoingByNode.get(args.startNodeId) ?? []) {
+      if (e.output !== "main") continue;
+      this.enqueueEdge(queue, {
+        batchId: args.batchId,
+        to: e.to,
+        from: { nodeId: args.startNodeId, output: "main" },
+        items: args.items,
+      });
+    }
+    return queue;
+  }
+
+  applyOutputs(
+    queue: RunQueueEntry[],
+    args: { fromNodeId: NodeId; outputs: Record<string, Items | undefined>; batchId: string },
+  ): void {
+    for (const e of this.topology.outgoingByNode.get(args.fromNodeId) ?? []) {
+      const outItems = (args.outputs as any)[e.output] ?? [];
+      this.enqueueEdge(queue, {
+        batchId: args.batchId,
+        to: e.to,
+        from: { nodeId: args.fromNodeId, output: e.output },
+        items: outItems,
+      });
+    }
+  }
+
+  nextActivation(queue: RunQueueEntry[]): PlannedActivation | null {
+    const readyCollect = this.resolveReadyCollect(queue);
+    if (readyCollect) {
+      return readyCollect;
+    }
+
+    const jobIdx = queue.findIndex((q) => !q.collect);
+    if (jobIdx === -1) {
+      if (queue.length === 0) return null;
+      const sealedCollect = this.resolveSealedCollect(queue);
+      if (sealedCollect) {
+        return sealedCollect;
+      }
+      const stuck = queue[0]!;
+      throw new Error(this.describeUnsatisfiedCollect(stuck));
+    }
+
+    const job = queue.splice(jobIdx, 1)[0]!;
+    const def = this.topology.defsById.get(job.nodeId);
+    if (!def || def.kind !== "node") return this.nextActivation(queue);
+    return { kind: "single", nodeId: job.nodeId, input: job.input, batchId: job.batchId ?? "batch_1" };
+  }
+
+  sumItemsByPort(inputsByPort: Readonly<Record<InputPortKey, Items>>): number {
+    let n = 0;
+    for (const v of Object.values(inputsByPort)) n += v?.length ?? 0;
+    return n;
+  }
+
+  private resolveReadyCollect(queue: RunQueueEntry[]): PlannedActivation | null {
+    for (let i = 0; i < queue.length; i++) {
+      const ready = this.tryDequeueCollect(queue, i);
+      if (ready) {
+        return ready;
+      }
+    }
+    return null;
+  }
+
+  private resolveSealedCollect(queue: RunQueueEntry[]): PlannedActivation | null {
+    for (let i = 0; i < queue.length; i++) {
+      const queueEntry = queue[i]!;
+      if (!queueEntry.collect) {
+        continue;
+      }
+      const received = queueEntry.collect.received as Record<InputPortKey, Items>;
+      if (Object.keys(received).length === 0) {
+        continue;
+      }
+      this.fillMissingCollectInputs(queueEntry);
+      const ready = this.tryDequeueCollect(queue, i);
+      if (ready) {
+        return ready;
+      }
+    }
+    return null;
+  }
+
+  private tryDequeueCollect(queue: RunQueueEntry[], index: number): PlannedActivation | null {
+    const queueEntry = queue[index]!;
+    if (!queueEntry.collect) {
+      return null;
+    }
+    const batchId = queueEntry.batchId ?? "batch_1";
+    const expected = queueEntry.collect.expectedInputs ?? [];
+    const received = queueEntry.collect.received as Record<InputPortKey, Items>;
+    for (const input of expected) {
+      if (!(input in received)) {
+        return null;
+      }
+    }
+    queue.splice(index, 1);
+    return { kind: "multi", nodeId: queueEntry.nodeId, inputsByPort: received, batchId };
+  }
+
+  private fillMissingCollectInputs(queueEntry: RunQueueEntry): void {
+    if (!queueEntry.collect) {
+      return;
+    }
+    const received = queueEntry.collect.received as Record<InputPortKey, Items>;
+    for (const input of queueEntry.collect.expectedInputs ?? []) {
+      if (!(input in received)) {
+        received[input] = [];
+      }
+    }
+  }
+
+  private enqueueEdge(
+    queue: RunQueueEntry[],
+    args: Readonly<{
+      batchId: string;
+      to: { nodeId: NodeId; input: InputPortKey };
+      from: { nodeId: NodeId; output: OutputPortKey };
+      items: Items;
+    }>,
+  ): void {
+    const target = this.nodeInstances.get(args.to.nodeId);
+    const isMulti = this.isMultiInputNode(target);
+
+    if (!isMulti) {
+      if (args.items.length === 0) {
+        if (this.shouldContinueAfterEmptyOutputFromSource(args.from.nodeId)) {
+          queue.push({
+            nodeId: args.to.nodeId,
+            input: args.items,
+            toInput: args.to.input,
+            batchId: args.batchId,
+            from: args.from,
+          });
+          return;
+        }
+        this.propagateEmptyPath(queue, args.to.nodeId, args.batchId);
+        return;
+      }
+      queue.push({
+        nodeId: args.to.nodeId,
+        input: args.items,
+        toInput: args.to.input,
+        batchId: args.batchId,
+        from: args.from,
+      });
+      return;
+    }
+
+    const expected = this.topology.expectedInputsByNode.get(args.to.nodeId) ?? [];
+    let collect = queue.find(
+      (q) => q.nodeId === args.to.nodeId && (q.batchId ?? "batch_1") === args.batchId && !!q.collect,
+    );
+    if (!collect) {
+      collect = {
+        nodeId: args.to.nodeId,
+        input: [],
+        batchId: args.batchId,
+        collect: { expectedInputs: expected, received: {} as Record<InputPortKey, Items> },
+      };
+      queue.push(collect);
+    }
+
+    const received = (collect.collect as any).received as Record<InputPortKey, Items>;
+    received[args.to.input] = args.items;
+  }
+
+  private shouldContinueAfterEmptyOutputFromSource(fromNodeId: NodeId): boolean {
+    const def = this.topology.defsById.get(fromNodeId);
+    if (!def) {
+      return false;
+    }
+    return def.config.continueWhenEmptyOutput === true;
+  }
+
+  private propagateEmptyPath(queue: RunQueueEntry[], nodeId: NodeId, batchId: string): void {
+    for (const edge of this.topology.outgoingByNode.get(nodeId) ?? []) {
+      this.enqueueEdge(queue, {
+        batchId,
+        to: edge.to,
+        from: { nodeId, output: edge.output },
+        items: [],
+      });
+    }
+  }
+
+  private isMultiInputNode(n: unknown): boolean {
+    return typeof (n as any)?.executeMulti === "function";
+  }
+
+  private describeUnsatisfiedCollect(queueEntry: RunQueueEntry): string {
+    const batchId = queueEntry.batchId ?? "batch_1";
+    const expectedInputs = queueEntry.collect?.expectedInputs ?? [];
+    const receivedInputs = Object.keys(
+      (queueEntry.collect?.received ?? {}) as Record<InputPortKey, Items>,
+    ) as InputPortKey[];
+    const missingInputs = expectedInputs.filter((input) => !receivedInputs.includes(input));
+    const mergeNodeLabel = this.formatNodeLabel(queueEntry.nodeId);
+    const receivedSummary = this.describeReceivedInputs(queueEntry);
+    const missingSummary = this.describeMissingInputs(queueEntry.nodeId, missingInputs);
+
+    return [
+      `Multi-input collect is stuck at ${mergeNodeLabel} (batchId=${batchId}).`,
+      `Expected inputs: ${this.formatInputList(expectedInputs)}.`,
+      `Received inputs: ${receivedSummary}.`,
+      `Missing inputs: ${missingSummary}.`,
+    ].join(" ");
+  }
+
+  private describeReceivedInputs(queueEntry: RunQueueEntry): string {
+    const received = (queueEntry.collect?.received ?? {}) as Record<InputPortKey, Items>;
+    const receivedEntries = Object.entries(received);
+    if (receivedEntries.length === 0) {
+      return "none";
+    }
+    return receivedEntries
+      .map(([input, items]) => `${input} (${items.length} item${items.length === 1 ? "" : "s"})`)
+      .join(", ");
+  }
+
+  private describeMissingInputs(nodeId: NodeId, missingInputs: ReadonlyArray<InputPortKey>): string {
+    if (missingInputs.length === 0) {
+      return "none";
+    }
+    return missingInputs
+      .map((input) => {
+        const sources = this.findSources(nodeId, input);
+        if (sources.length === 0) {
+          return input;
+        }
+        return `${input} from ${sources.join(" or ")}`;
+      })
+      .join(", ");
+  }
+
+  private findSources(nodeId: NodeId, input: InputPortKey): string[] {
+    const matches: string[] = [];
+    for (const [sourceNodeId, edges] of this.topology.outgoingByNode.entries()) {
+      for (const edge of edges) {
+        if (edge.to.nodeId === nodeId && edge.to.input === input) {
+          matches.push(this.formatNodeLabel(sourceNodeId));
+        }
+      }
+    }
+    return matches;
+  }
+
+  private formatInputList(inputs: ReadonlyArray<InputPortKey>): string {
+    return inputs.length > 0 ? `[${inputs.join(", ")}]` : "[]";
+  }
+
+  private formatNodeLabel(nodeId: NodeId): string {
+    const definition = this.topology.defsById.get(nodeId);
+    const instance = this.nodeInstances.get(nodeId);
+    const typeName =
+      definition?.type && typeof definition.type === "function"
+        ? definition.type.name
+        : instance && typeof instance === "object" && "constructor" in instance
+          ? ((instance.constructor as { name?: string }).name ?? "Node")
+          : "Node";
+    return definition?.name ? `"${definition.name}" (${typeName}:${nodeId})` : `${typeName}:${nodeId}`;
+  }
+}

package/src/planning/WorkflowTopologyPlanner.ts

@@ -0,0 +1,77 @@
+import type { InputPortKey, NodeId, OutputPortKey, WorkflowDefinition } from "../types";
+import { WorkflowExecutableNodeClassifierFactory } from "../workflow/definition/WorkflowExecutableNodeClassifierFactory";
+
+type NodeDef = WorkflowDefinition["nodes"][number];
+
+export class WorkflowTopology {
+  private constructor(
+    public readonly defsById: ReadonlyMap<NodeId, NodeDef>,
+    public readonly outgoingByNode: ReadonlyMap<
+      NodeId,
+      ReadonlyArray<Readonly<{ output: OutputPortKey; to: Readonly<{ nodeId: NodeId; input: InputPortKey }> }>>
+    >,
+    public readonly incomingByNode: ReadonlyMap<
+      NodeId,
+      ReadonlyArray<Readonly<{ from: Readonly<{ nodeId: NodeId; output: OutputPortKey }>; input: InputPortKey }>>
+    >,
+    public readonly expectedInputsByNode: ReadonlyMap<NodeId, ReadonlyArray<InputPortKey>>,
+    public readonly rootNodeIds: ReadonlyArray<NodeId>,
+  ) {}
+
+  static fromWorkflow(wf: WorkflowDefinition): WorkflowTopology {
+    const classifier = WorkflowExecutableNodeClassifierFactory.create(wf);
+    const defs = new Map<NodeId, NodeDef>();
+    for (const n of wf.nodes) {
+      if (classifier.isExecutableNodeId(n.id)) defs.set(n.id, n);
+    }
+
+    const outgoing = new Map<
+      NodeId,
+      Array<Readonly<{ output: OutputPortKey; to: Readonly<{ nodeId: NodeId; input: InputPortKey }> }>>
+    >();
+    for (const e of wf.edges) {
+      if (!classifier.isExecutableNodeId(e.from.nodeId) || !classifier.isExecutableNodeId(e.to.nodeId)) {
+        continue;
+      }
+      const list = outgoing.get(e.from.nodeId) ?? [];
+      list.push({ output: e.from.output, to: { nodeId: e.to.nodeId, input: e.to.input } });
+      outgoing.set(e.from.nodeId, list);
+    }
+
+    const incomingByNode = new Map<
+      NodeId,
+      Array<Readonly<{ from: Readonly<{ nodeId: NodeId; output: OutputPortKey }>; input: InputPortKey }>>
+    >();
+    for (const e of wf.edges) {
+      if (!classifier.isExecutableNodeId(e.from.nodeId) || !classifier.isExecutableNodeId(e.to.nodeId)) {
+        continue;
+      }
+      const list = incomingByNode.get(e.to.nodeId) ?? [];
+      list.push({ from: { nodeId: e.from.nodeId, output: e.from.output }, input: e.to.input });
+      incomingByNode.set(e.to.nodeId, list);
+    }
+
+    const expected = new Map<NodeId, InputPortKey[]>();
+    for (const [toNodeId, inputs] of incomingByNode.entries()) {
+      const counts = new Map<InputPortKey, number>();
+      for (const edge of inputs) counts.set(edge.input, (counts.get(edge.input) ?? 0) + 1);
+      for (const [k, n] of counts.entries()) {
+        if (n > 1) throw new Error(`Node ${toNodeId} has multiple edges into input '${k}'. Use a Merge node upstream.`);
+      }
+
+      const order: InputPortKey[] = [];
+      const seen = new Set<InputPortKey>();
+      for (const edge of inputs) {
+        if (seen.has(edge.input)) continue;
+        seen.add(edge.input);
+        order.push(edge.input);
+      }
+      expected.set(toNodeId, order);
+    }
+
+    const rootNodeIds = wf.nodes
+      .filter((node) => classifier.isExecutableNodeId(node.id) && !incomingByNode.has(node.id))
+      .map((node) => node.id);
+    return new WorkflowTopology(defs, outgoing, incomingByNode, expected, rootNodeIds);
+  }
+}

package/src/planning/index.ts

@@ -0,0 +1,4 @@
+export { CurrentStateFrontierPlanner } from "./CurrentStateFrontierPlanner";
+export { EngineWorkflowPlanningFactory } from "./EngineWorkflowPlanningFactory";
+export { RunQueuePlanner } from "./RunQueuePlanner";
+export { WorkflowTopology } from "./WorkflowTopologyPlanner";

package/src/policies/WorkflowPolicyErrorServices.ts

@@ -0,0 +1,38 @@
+import type { TypeToken } from "../di";
+import type {
+  NodeErrorHandler,
+  NodeErrorHandlerSpec,
+  NodeResolver,
+  WorkflowErrorHandler,
+  WorkflowErrorHandlerSpec,
+} from "../types";
+
+export class WorkflowPolicyErrorServices {
+  constructor(private readonly nodeResolver: NodeResolver) {}
+
+  resolveNodeErrorHandler(spec: NodeErrorHandlerSpec | undefined): NodeErrorHandler | undefined {
+    if (!spec) return undefined;
+    if (
+      typeof spec === "object" &&
+      spec !== null &&
+      "handle" in spec &&
+      typeof (spec as NodeErrorHandler).handle === "function"
+    ) {
+      return spec as NodeErrorHandler;
+    }
+    return this.nodeResolver.resolve(spec as TypeToken<NodeErrorHandler>);
+  }
+
+  resolveWorkflowErrorHandler(spec: WorkflowErrorHandlerSpec | undefined): WorkflowErrorHandler | undefined {
+    if (!spec) return undefined;
+    if (
+      typeof spec === "object" &&
+      spec !== null &&
+      "onError" in spec &&
+      typeof (spec as WorkflowErrorHandler).onError === "function"
+    ) {
+      return spec as WorkflowErrorHandler;
+    }
+    return this.nodeResolver.resolve(spec as TypeToken<WorkflowErrorHandler>);
+  }
+}

package/src/policies/executionLimits/EngineExecutionLimitsPolicy.ts

@@ -0,0 +1,66 @@
+import type { ParentExecutionRef, RunExecutionOptions } from "../../types";
+
+export interface EngineExecutionLimitsPolicyConfig {
+  readonly defaultMaxNodeActivations: number;
+  readonly hardMaxNodeActivations: number;
+  readonly defaultMaxSubworkflowDepth: number;
+  readonly hardMaxSubworkflowDepth: number;
+}
+
+/** Framework defaults for {@link EngineExecutionLimitsPolicy} (merged with host `runtime.engineExecutionLimits`). */
+export const ENGINE_EXECUTION_LIMITS_DEFAULTS: EngineExecutionLimitsPolicyConfig = {
+  defaultMaxNodeActivations: 100_000,
+  hardMaxNodeActivations: 100_000,
+  defaultMaxSubworkflowDepth: 32,
+  hardMaxSubworkflowDepth: 32,
+};
+
+/**
+ * Resolves per-run execution limits: defaults, hard ceilings, and subworkflow depth for new runs.
+ */
+export class EngineExecutionLimitsPolicy {
+  constructor(private readonly config: EngineExecutionLimitsPolicyConfig = ENGINE_EXECUTION_LIMITS_DEFAULTS) {}
+
+  /**
+   * Effective options for a new root run (depth 0): defaults merged with engine ceilings.
+   * Replaces a separate one-method factory for root-run bootstrap.
+   */
+  createRootExecutionOptions(): RunExecutionOptions {
+    return this.mergeExecutionOptionsForNewRun(undefined, undefined);
+  }
+
+  mergeExecutionOptionsForNewRun(
+    parent: ParentExecutionRef | undefined,
+    user: RunExecutionOptions | undefined,
+  ): RunExecutionOptions {
+    const subworkflowDepth = parent === undefined ? 0 : (parent.subworkflowDepth ?? 0) + 1;
+    const inheritedMaxNode = parent?.engineMaxNodeActivations;
+    const inheritedMaxSub = parent?.engineMaxSubworkflowDepth;
+    const maxNodeActivations = this.capNumber(
+      user?.maxNodeActivations ?? inheritedMaxNode,
+      this.config.defaultMaxNodeActivations,
+      this.config.hardMaxNodeActivations,
+    );
+    const maxSubworkflowDepth = this.capNumber(
+      user?.maxSubworkflowDepth ?? inheritedMaxSub,
+      this.config.defaultMaxSubworkflowDepth,
+      this.config.hardMaxSubworkflowDepth,
+    );
+    if (subworkflowDepth > maxSubworkflowDepth) {
+      throw new Error(
+        `Subworkflow nesting depth ${subworkflowDepth} exceeds maxSubworkflowDepth ${maxSubworkflowDepth} (run would be a child of parent run).`,
+      );
+    }
+    return {
+      ...user,
+      subworkflowDepth,
+      maxNodeActivations,
+      maxSubworkflowDepth,
+    };
+  }
+
+  private capNumber(requested: number | undefined, defaultValue: number, hardCeiling: number): number {
+    const base = requested === undefined ? defaultValue : requested;
+    return Math.min(base, hardCeiling);
+  }
+}

package/src/policies/executionLimits/EngineExecutionLimitsPolicyFactory.ts

@@ -0,0 +1,14 @@
+import {
+  EngineExecutionLimitsPolicy,
+  ENGINE_EXECUTION_LIMITS_DEFAULTS,
+  type EngineExecutionLimitsPolicyConfig,
+} from "./EngineExecutionLimitsPolicy";
+
+/**
+ * Builds {@link EngineExecutionLimitsPolicy} by merging {@link ENGINE_EXECUTION_LIMITS_DEFAULTS} with optional `overrides` (e.g. host `runtime.engineExecutionLimits`).
+ */
+export class EngineExecutionLimitsPolicyFactory {
+  create(overrides?: Partial<EngineExecutionLimitsPolicyConfig>): EngineExecutionLimitsPolicy {
+    return new EngineExecutionLimitsPolicy({ ...ENGINE_EXECUTION_LIMITS_DEFAULTS, ...overrides });
+  }
+}

package/src/policies/index.ts

@@ -0,0 +1,10 @@
+export {
+  ENGINE_EXECUTION_LIMITS_DEFAULTS,
+  EngineExecutionLimitsPolicy,
+  type EngineExecutionLimitsPolicyConfig,
+} from "./executionLimits/EngineExecutionLimitsPolicy";
+export { EngineExecutionLimitsPolicyFactory } from "./executionLimits/EngineExecutionLimitsPolicyFactory";
+export { RunPolicySnapshotFactory } from "./storage/RunPolicySnapshotFactory";
+export { RunTerminalPersistenceCoordinator } from "./storage/RunTerminalPersistenceCoordinator";
+export { WorkflowPolicyErrorServices } from "./WorkflowPolicyErrorServices";
+export { WorkflowStoragePolicyEvaluator } from "./storage/WorkflowStoragePolicyEvaluator";

package/src/policies/storage/RunPolicySnapshotFactory.ts

@@ -0,0 +1,23 @@
+import type {
+  PersistedRunPolicySnapshot,
+  WorkflowDefinition,
+  WorkflowPolicyRuntimeDefaults,
+  WorkflowStoragePolicyMode,
+} from "../../types";
+
+export class RunPolicySnapshotFactory {
+  static create(workflow: WorkflowDefinition, defaults?: WorkflowPolicyRuntimeDefaults): PersistedRunPolicySnapshot {
+    const prune = workflow.prunePolicy;
+    const retentionSeconds = prune?.runDataRetentionSeconds ?? defaults?.retentionSeconds;
+    const binaryRetentionSeconds = prune?.binaryRetentionSeconds ?? defaults?.binaryRetentionSeconds;
+    const storagePolicy: WorkflowStoragePolicyMode =
+      typeof workflow.storagePolicy === "string"
+        ? (workflow.storagePolicy as WorkflowStoragePolicyMode)
+        : (defaults?.storagePolicy ?? "ALL");
+    return {
+      retentionSeconds,
+      binaryRetentionSeconds,
+      storagePolicy,
+    };
+  }
+}

package/src/policies/storage/RunTerminalPersistenceCoordinator.ts

@@ -0,0 +1,29 @@
+import type { PersistedRunState, WorkflowDefinition, WorkflowExecutionRepository } from "../../types";
+
+import { WorkflowStoragePolicyEvaluator } from "./WorkflowStoragePolicyEvaluator";
+
+export class RunTerminalPersistenceCoordinator {
+  constructor(
+    private readonly runRepository: WorkflowExecutionRepository,
+    private readonly storageEvaluator: WorkflowStoragePolicyEvaluator,
+  ) {}
+
+  async maybeDeleteAfterTerminalState(args: {
+    workflow: WorkflowDefinition;
+    state: PersistedRunState;
+    finalStatus: "completed" | "failed";
+    finishedAt: string;
+  }): Promise<void> {
+    const persist = await this.storageEvaluator.shouldPersist(args.workflow, args.state.policySnapshot, {
+      runId: args.state.runId,
+      workflowId: args.state.workflowId,
+      workflow: args.workflow,
+      finalStatus: args.finalStatus,
+      startedAt: args.state.startedAt,
+      finishedAt: args.finishedAt,
+    });
+    if (persist) return;
+    if (!this.runRepository.deleteRun) return;
+    await this.runRepository.deleteRun(args.state.runId);
+  }
+}

package/src/policies/storage/WorkflowStoragePolicyEvaluator.ts

@@ -0,0 +1,39 @@
+import type { TypeToken } from "../../di";
+import type {
+  NodeResolver,
+  PersistedRunPolicySnapshot,
+  WorkflowDefinition,
+  WorkflowStoragePolicyDecisionArgs,
+  WorkflowStoragePolicyMode,
+  WorkflowStoragePolicyResolver,
+} from "../../types";
+
+export class WorkflowStoragePolicyEvaluator {
+  constructor(private readonly nodeResolver: NodeResolver) {}
+
+  async shouldPersist(
+    workflow: WorkflowDefinition,
+    snapshot: PersistedRunPolicySnapshot | undefined,
+    args: WorkflowStoragePolicyDecisionArgs,
+  ): Promise<boolean> {
+    const spec = workflow.storagePolicy;
+    if (spec === undefined) {
+      return this.modeMatches(snapshot?.storagePolicy ?? "ALL", args);
+    }
+    if (typeof spec === "string") {
+      return this.modeMatches(spec as WorkflowStoragePolicyMode, args);
+    }
+    const resolver = this.nodeResolver.resolve(
+      spec as TypeToken<WorkflowStoragePolicyResolver>,
+    ) as WorkflowStoragePolicyResolver;
+    return Boolean(await resolver.shouldPersist(args));
+  }
+
+  private modeMatches(mode: WorkflowStoragePolicyMode, args: WorkflowStoragePolicyDecisionArgs): boolean {
+    if (mode === "ALL") return true;
+    if (mode === "NEVER") return false;
+    if (mode === "SUCCESS") return args.finalStatus === "completed";
+    if (mode === "ERROR") return args.finalStatus === "failed";
+    return true;
+  }
+}