@codemation/core 0.0.1

package/src/contracts/runtimeTypes.ts

@@ -0,0 +1,373 @@
+import type { ReadableStream as BinaryReadableStream } from "node:stream/web";
+import type { TypeToken } from "../di";
+import type { RunEventBus } from "../events/runEvents";
+import type { CredentialSessionService } from "./credentialTypes";
+import type {
+  ConnectionInvocationAppendArgs,
+  NodeInputsByPort,
+  PersistedWorkflowSnapshot,
+  PersistedWorkflowTokenRegistryLike,
+  RunExecutionOptions,
+  RunResult,
+  WorkflowExecutionRepository,
+} from "./runTypes";
+import type { WorkflowActivationPolicy } from "./workflowActivationPolicy";
+import type { TriggerInstanceId, WebhookTriggerMatcher } from "./webhookTypes";
+import type {
+  ActivationIdFactory,
+  BinaryAttachment,
+  Item,
+  Items,
+  JsonValue,
+  NodeActivationId,
+  NodeConfigBase,
+  NodeId,
+  NodeOutputs,
+  OutputPortKey,
+  ParentExecutionRef,
+  RunDataFactory,
+  RunDataSnapshot,
+  RunId,
+  RunIdFactory,
+  TriggerNodeConfig,
+  TriggerNodeSetupState,
+  WorkflowDefinition,
+  WorkflowId,
+  WorkflowPolicyRuntimeDefaults,
+} from "./workflowTypes";
+
+export interface WorkflowRunnerService {
+  runById(args: {
+    workflowId: WorkflowId;
+    startAt?: NodeId;
+    items: Items;
+    parent?: ParentExecutionRef;
+  }): Promise<RunResult>;
+}
+
+export interface WorkflowRunnerResolver {
+  resolve(): WorkflowRunnerService | undefined;
+}
+
+export interface WorkflowRepository {
+  list(): ReadonlyArray<WorkflowDefinition>;
+  get(workflowId: WorkflowId): WorkflowDefinition | undefined;
+}
+
+export interface LiveWorkflowRepository extends WorkflowRepository {
+  setWorkflows(workflows: ReadonlyArray<WorkflowDefinition>): void;
+}
+
+export interface NodeResolver {
+  resolve<T>(token: TypeToken<T>): T;
+}
+
+export interface NodeExecutionStatePublisher {
+  markQueued(args: { nodeId: NodeId; activationId?: NodeActivationId; inputsByPort?: NodeInputsByPort }): Promise<void>;
+  markRunning(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+  }): Promise<void>;
+  markCompleted(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+    outputs?: NodeOutputs;
+  }): Promise<void>;
+  markFailed(args: {
+    nodeId: NodeId;
+    activationId?: NodeActivationId;
+    inputsByPort?: NodeInputsByPort;
+    error: Error;
+  }): Promise<void>;
+  appendConnectionInvocation(args: ConnectionInvocationAppendArgs): Promise<void>;
+}
+
+export type BinaryBody = BinaryReadableStream<Uint8Array> | AsyncIterable<Uint8Array> | Uint8Array | ArrayBuffer;
+
+export interface BinaryStorageWriteRequest {
+  storageKey: string;
+  body: BinaryBody;
+}
+
+export interface BinaryStorageWriteResult {
+  storageKey: string;
+  size: number;
+  sha256?: string;
+}
+
+export interface BinaryStorageReadResult {
+  body: BinaryReadableStream<Uint8Array>;
+  size?: number;
+}
+
+export interface BinaryStorageStatResult {
+  exists: boolean;
+  size?: number;
+}
+
+export interface BinaryStorage {
+  readonly driverName: string;
+  write(args: BinaryStorageWriteRequest): Promise<BinaryStorageWriteResult>;
+  openReadStream(storageKey: string): Promise<BinaryStorageReadResult | undefined>;
+  stat(storageKey: string): Promise<BinaryStorageStatResult>;
+  delete(storageKey: string): Promise<void>;
+}
+
+export interface BinaryAttachmentCreateRequest {
+  name: string;
+  body: BinaryBody;
+  mimeType: string;
+  filename?: string;
+  previewKind?: BinaryAttachment["previewKind"];
+}
+
+export interface NodeBinaryAttachmentService extends ExecutionBinaryService {
+  attach(args: BinaryAttachmentCreateRequest): Promise<BinaryAttachment>;
+  withAttachment<TJson>(item: Item<TJson>, name: string, attachment: BinaryAttachment): Item<TJson>;
+}
+
+export interface ExecutionBinaryService {
+  forNode(args: { nodeId: NodeId; activationId: NodeActivationId }): NodeBinaryAttachmentService;
+  openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined>;
+}
+
+export interface ExecutionContext {
+  runId: RunId;
+  workflowId: WorkflowId;
+  parent?: ParentExecutionRef;
+  /** This run's subworkflow depth (0 = root). */
+  subworkflowDepth: number;
+  /** Effective activation budget cap for this run (after policy merge). */
+  engineMaxNodeActivations: number;
+  /** Effective subworkflow nesting cap for this run (after policy merge). */
+  engineMaxSubworkflowDepth: number;
+  now: () => Date;
+  data: RunDataSnapshot;
+  nodeState?: NodeExecutionStatePublisher;
+  binary: ExecutionBinaryService;
+  getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+}
+
+export interface ExecutionContextFactory {
+  create(args: {
+    runId: RunId;
+    workflowId: WorkflowId;
+    parent?: ParentExecutionRef;
+    subworkflowDepth: number;
+    engineMaxNodeActivations: number;
+    engineMaxSubworkflowDepth: number;
+    data: RunDataSnapshot;
+    nodeState?: NodeExecutionStatePublisher;
+    getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+  }): ExecutionContext;
+}
+
+export interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
+  nodeId: NodeId;
+  activationId: NodeActivationId;
+  config: TConfig;
+  binary: NodeBinaryAttachmentService;
+}
+
+export interface TriggerSetupContext<
+  TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>,
+  TSetupState extends JsonValue | undefined = TriggerNodeSetupState<TConfig>,
+> extends ExecutionContext {
+  trigger: TriggerInstanceId;
+  config: TConfig;
+  previousState: TSetupState;
+  registerCleanup(cleanup: TriggerCleanupHandle): void;
+  emit(items: Items): Promise<void>;
+}
+
+export interface TriggerTestItemsContext<
+  TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>,
+  TSetupState extends JsonValue | undefined = TriggerNodeSetupState<TConfig>,
+> extends ExecutionContext {
+  trigger: TriggerInstanceId;
+  nodeId: NodeId;
+  config: TConfig;
+  previousState: TSetupState;
+}
+
+/**
+ * Trigger setup state is intentionally engine-owned so future ownership and
+ * leader-election metadata can be coordinated centrally rather than pushed into
+ * package-level setup code.
+ */
+
+export interface PersistedTriggerSetupState<TState extends JsonValue | undefined = JsonValue | undefined> {
+  trigger: TriggerInstanceId;
+  updatedAt: string;
+  state: TState;
+}
+
+export interface TriggerSetupStateRepository {
+  load(trigger: TriggerInstanceId): Promise<PersistedTriggerSetupState | undefined>;
+  save(state: PersistedTriggerSetupState): Promise<void>;
+  delete(trigger: TriggerInstanceId): Promise<void>;
+}
+
+export interface TriggerCleanupHandle {
+  stop(): Promise<void> | void;
+}
+
+export interface EngineHost {
+  credentialSessions: CredentialSessionService;
+  workflows?: WorkflowRunnerService;
+}
+
+export interface Node<TConfig extends NodeConfigBase = NodeConfigBase> {
+  kind: "node";
+  outputPorts: ReadonlyArray<OutputPortKey>;
+  execute(items: Items, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
+}
+
+export interface MultiInputNode<TConfig extends NodeConfigBase = NodeConfigBase> {
+  kind: "node";
+  outputPorts: ReadonlyArray<OutputPortKey>;
+  executeMulti(inputsByPort: NodeInputsByPort, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
+}
+
+export type TriggerSetupStateFor<TConfig extends TriggerNodeConfig<any, any>> = TriggerNodeSetupState<TConfig>;
+
+export interface TriggerNode<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>> {
+  kind: "trigger";
+  outputPorts: readonly ["main"];
+  setup(ctx: TriggerSetupContext<TConfig>): Promise<TriggerSetupStateFor<TConfig>>;
+  execute(items: Items, ctx: NodeExecutionContext<TConfig>): Promise<NodeOutputs>;
+}
+
+export interface TestableTriggerNode<
+  TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>,
+> extends TriggerNode<TConfig> {
+  getTestItems(ctx: TriggerTestItemsContext<TConfig>): Promise<Items>;
+}
+
+export type ExecutableTriggerNode<TConfig extends TriggerNodeConfig<any, any> = TriggerNodeConfig<any, any>> =
+  TriggerNode<TConfig>;
+
+export interface NodeExecutionRequest {
+  runId: RunId;
+  activationId: NodeActivationId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  input: Items;
+  parent?: ParentExecutionRef;
+  queue?: string;
+  executionOptions?: RunExecutionOptions;
+}
+
+export interface NodeExecutionScheduler {
+  enqueue(request: NodeExecutionRequest): Promise<{ receiptId: string }>;
+  cancel?(receiptId: string): Promise<void>;
+}
+
+export type NodeActivationRequestBase = Readonly<{
+  runId: RunId;
+  activationId: NodeActivationId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  parent?: ParentExecutionRef;
+  executionOptions?: RunExecutionOptions;
+  batchId?: string;
+  ctx: NodeExecutionContext;
+}>;
+
+export type NodeActivationRequest =
+  | (NodeActivationRequestBase &
+      Readonly<{
+        kind: "single";
+        input: Items;
+      }>)
+  | (NodeActivationRequestBase &
+      Readonly<{
+        kind: "multi";
+        inputsByPort: NodeInputsByPort;
+      }>);
+
+export interface NodeActivationReceipt {
+  receiptId: string;
+  mode?: "local" | "worker";
+  queue?: string;
+}
+
+export interface NodeActivationContinuation {
+  markNodeRunning(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    inputsByPort: NodeInputsByPort;
+  }): Promise<void>;
+  resumeFromNodeResult(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    outputs: NodeOutputs;
+  }): Promise<RunResult>;
+  resumeFromNodeError(args: {
+    runId: RunId;
+    activationId: NodeActivationId;
+    nodeId: NodeId;
+    error: Error;
+  }): Promise<RunResult>;
+}
+
+export interface NodeActivationScheduler {
+  setContinuation?(continuation: NodeActivationContinuation): void;
+  enqueue(request: NodeActivationRequest): Promise<NodeActivationReceipt>;
+  notifyPendingStatePersisted?(runId: RunId): void;
+  cancel?(receiptId: string): Promise<void>;
+}
+
+export interface WorkflowNodeInstanceFactory {
+  createNodes(workflow: WorkflowDefinition): ReadonlyMap<NodeId, unknown>;
+  createByType(type: TypeToken<unknown>): unknown;
+}
+
+export interface NodeExecutor {
+  execute(request: NodeActivationRequest): Promise<NodeOutputs>;
+}
+
+export interface WorkflowSnapshotFactory {
+  create(workflow: WorkflowDefinition): PersistedWorkflowSnapshot;
+}
+
+export interface WorkflowSnapshotResolver {
+  resolve(args: {
+    workflowId: WorkflowId;
+    workflowSnapshot?: PersistedWorkflowSnapshot;
+  }): WorkflowDefinition | undefined;
+}
+
+/** Optional host wiring for trigger lifecycle logs (boot skip + activation sync). */
+export interface TriggerRuntimeDiagnostics {
+  info(message: string): void;
+  warn(message: string): void;
+}
+
+export interface EngineDeps {
+  credentialSessions: CredentialSessionService;
+  liveWorkflowRepository: LiveWorkflowRepository;
+  workflowRepository: WorkflowRepository;
+  /** When {@link AllWorkflowsActiveWorkflowActivationPolicy}, all workflows behave as active (tests). */
+  workflowActivationPolicy: WorkflowActivationPolicy;
+  nodeResolver: NodeResolver;
+  triggerSetupStateRepository: TriggerSetupStateRepository;
+  webhookTriggerMatcher: WebhookTriggerMatcher;
+  runIdFactory: RunIdFactory;
+  activationIdFactory: ActivationIdFactory;
+  workflowExecutionRepository: WorkflowExecutionRepository;
+  activationScheduler: NodeActivationScheduler;
+  runDataFactory: RunDataFactory;
+  executionContextFactory: ExecutionContextFactory;
+  eventBus?: RunEventBus;
+  tokenRegistry: PersistedWorkflowTokenRegistryLike;
+  workflowNodeInstanceFactory: WorkflowNodeInstanceFactory;
+  /** Defaults for prune/storage snapshot when workflow omits explicit policy fields. */
+  workflowPolicyRuntimeDefaults?: WorkflowPolicyRuntimeDefaults;
+  /** When set, logs inactive-workflow skips at boot and trigger start/stop on activation changes. */
+  triggerRuntimeDiagnostics?: TriggerRuntimeDiagnostics;
+}

package/src/contracts/webhookTypes.ts

@@ -0,0 +1,49 @@
+import type { Items, NodeId, WorkflowId } from "./workflowTypes";
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export interface WebhookControlSignal {
+  readonly __webhookControl: true;
+  readonly kind: "respondNow" | "respondNowAndContinue";
+  readonly responseItems: Items;
+  readonly continueItems?: Items;
+}
+
+export interface WebhookTriggerRoutingDiagnostics {
+  warn(message: string): void;
+  /** Inactive workflows omitted from the webhook route index (optional; host should wire for clarity at boot/reload). */
+  info?(message: string): void;
+}
+
+export interface TriggerInstanceId {
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+}
+
+/** Match for an incoming HTTP request: user-defined URL segment + workflow trigger node. */
+export interface WebhookInvocationMatch {
+  /** Same value as the webhook trigger's configured endpoint key (URL segment under the webhook base path). */
+  endpointPath: string;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  methods: ReadonlyArray<HttpMethod>;
+  parseJsonBody?: (body: unknown) => unknown;
+}
+
+/** Result of resolving an HTTP method + endpoint path against the catalog webhook index (404 vs 405 vs match). */
+export type WebhookTriggerResolution =
+  | { status: "notFound" }
+  | { status: "methodNotAllowed"; match: WebhookInvocationMatch }
+  | { status: "ok"; match: WebhookInvocationMatch };
+
+/**
+ * Resolves webhook routes from workflow definitions (catalog-backed index, no registration at trigger setup).
+ */
+export interface WebhookTriggerMatcher {
+  match(args: { endpointPath: string; method: HttpMethod }): WebhookInvocationMatch | undefined;
+  lookup(endpointPath: string): WebhookInvocationMatch | undefined;
+  onEngineWorkflowsLoaded?(): void;
+  onEngineStopped?(): void;
+  /** Rebuild route index after activation changes without stopping the engine. */
+  reloadWebhookRoutes?(): void;
+}

package/src/contracts/workflowActivationPolicy.ts

@@ -0,0 +1,16 @@
+import type { WorkflowId } from "./workflowTypes";
+
+/**
+ * Host-controlled policy: when false, trigger {@link TriggerNode} setup is skipped and webhook routes
+ * for that workflow are not registered (see engine trigger runtime + webhook matcher).
+ */
+export interface WorkflowActivationPolicy {
+  isActive(workflowId: WorkflowId): boolean;
+}
+
+/** Default for tests and harnesses: every workflow is treated as active (legacy behavior). */
+export class AllWorkflowsActiveWorkflowActivationPolicy implements WorkflowActivationPolicy {
+  isActive(_workflowId: WorkflowId): boolean {
+    return true;
+  }
+}