@codemation/core 0.0.1

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@codemation/core",
+  "version": "0.0.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Made Relevant B.V.",
+  "homepage": "https://www.maderelevant.com",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": {
+        "import": "./src/index.ts",
+        "require": "./dist/index.cjs"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./browser": {
+      "types": "./src/browser.ts",
+      "import": "./src/browser.ts"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "development": {
+        "import": "./src/testing.ts",
+        "require": "./dist/testing.cjs"
+      },
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs"
+    },
+    "./bootstrap": {
+      "types": "./dist/bootstrap/index.d.ts",
+      "development": {
+        "import": "./src/bootstrap/index.ts",
+        "require": "./dist/bootstrap/index.cjs"
+      },
+      "import": "./dist/bootstrap/index.js",
+      "require": "./dist/bootstrap/index.cjs"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "eslint": "^10.0.3",
+    "tsdown": "^0.15.5",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "4.0.18"
+  },
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "tsyringe": "^4.10.0",
+    "zod": "^4.3.6"
+  },
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "pnpm build && vitest run"
+  }
+}

package/src/ai/AiHost.ts

@@ -0,0 +1,115 @@
+import type { TypeToken } from "../di";
+
+import type { CredentialRequirement } from "../contracts/credentialTypes";
+
+import type { Item, Items, NodeConfigBase, NodeExecutionContext, RunnableNodeConfig } from "../types";
+
+import type { input as ZodInput, output as ZodOutput, ZodType } from "zod";
+
+export interface AgentCanvasPresentation<TIcon extends string = string> {
+  readonly label?: string;
+  readonly icon?: TIcon;
+}
+
+export type ZodSchemaAny = ZodType<any, any, any>;
+
+export interface ToolConfig {
+  readonly type: TypeToken<Tool<ToolConfig, ZodSchemaAny, ZodSchemaAny>>;
+  readonly name: string;
+  readonly description?: string;
+  readonly presentation?: AgentCanvasPresentation;
+  getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
+}
+
+export type ToolExecuteArgs<TConfig extends ToolConfig = ToolConfig, TInput = unknown> = Readonly<{
+  config: TConfig;
+  input: TInput;
+  ctx: NodeExecutionContext<any>;
+  item: Item;
+  itemIndex: number;
+  items: Items;
+}>;
+
+export interface Tool<
+  TConfig extends ToolConfig = ToolConfig,
+  TInputSchema extends ZodSchemaAny = ZodSchemaAny,
+  TOutputSchema extends ZodSchemaAny = ZodSchemaAny,
+> {
+  readonly defaultDescription: string;
+  readonly inputSchema: TInputSchema;
+  readonly outputSchema: TOutputSchema;
+  execute(
+    args: ToolExecuteArgs<TConfig, ZodInput<TInputSchema>>,
+  ): Promise<ZodOutput<TOutputSchema>> | ZodOutput<TOutputSchema>;
+}
+
+export type AgentTool<
+  TInputSchema extends ZodSchemaAny = ZodSchemaAny,
+  TOutputSchema extends ZodSchemaAny = ZodSchemaAny,
+> = Tool<ToolConfig, TInputSchema, TOutputSchema>;
+
+export type AgentToolExecuteArgs<TInput = unknown> = ToolExecuteArgs<ToolConfig, TInput>;
+
+export type AgentToolToken = TypeToken<Tool<ToolConfig, ZodSchemaAny, ZodSchemaAny>>;
+
+export interface AgentToolDefinition {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: ZodSchemaAny;
+}
+
+export type AgentToolCall = Readonly<{ id?: string; name: string; input: unknown }>;
+
+export type AgentToolCallPlanner<_TNodeConfig = unknown> = (
+  item: Item,
+  index: number,
+  items: Items,
+  ctx: NodeExecutionContext<any>,
+) => ReadonlyArray<AgentToolCall>;
+
+export interface ChatModelConfig {
+  readonly type: TypeToken<ChatModelFactory<ChatModelConfig>>;
+  readonly name: string;
+  readonly presentation?: AgentCanvasPresentation;
+  getCredentialRequirements?(): ReadonlyArray<CredentialRequirement>;
+}
+
+export interface LangChainChatModelLike {
+  invoke(input: unknown, options?: unknown): Promise<unknown>;
+  bindTools?(tools: ReadonlyArray<unknown>): LangChainChatModelLike;
+}
+
+export interface ChatModelFactory<TConfig extends ChatModelConfig = ChatModelConfig> {
+  create(
+    args: Readonly<{ config: TConfig; ctx: NodeExecutionContext<any> }>,
+  ): Promise<LangChainChatModelLike> | LangChainChatModelLike;
+}
+
+export interface AgentNodeConfig<TInputJson = unknown, TOutputJson = unknown> extends RunnableNodeConfig<
+  TInputJson,
+  TOutputJson
+> {
+  readonly systemMessage: string;
+  readonly userMessageFormatter: (
+    item: Item<TInputJson>,
+    index: number,
+    items: Items<TInputJson>,
+    ctx: NodeExecutionContext<any>,
+  ) => string;
+  readonly chatModel: ChatModelConfig;
+  readonly tools?: ReadonlyArray<ToolConfig>;
+}
+
+export class AgentConfigInspector {
+  static isAgentNodeConfig(config: NodeConfigBase | undefined): config is AgentNodeConfig<any, any> {
+    if (!config) return false;
+    const candidate = config as Partial<AgentNodeConfig<any, any>>;
+    return (
+      typeof candidate.systemMessage === "string" &&
+      typeof candidate.userMessageFormatter === "function" &&
+      !!candidate.chatModel
+    );
+  }
+}
+
+export type AgentAttachmentRole = "languageModel" | "tool";

package/src/binaries/DefaultExecutionBinaryServiceFactory.ts

@@ -0,0 +1,37 @@
+import type { BinaryAttachment, NodeActivationId, NodeId, RunId, WorkflowId } from "../types";
+
+import type {
+  BinaryStorage,
+  BinaryStorageReadResult,
+  ExecutionBinaryService,
+  NodeBinaryAttachmentService,
+} from "../types";
+
+import { DefaultNodeBinaryAttachmentService } from "./DefaultNodeBinaryAttachmentServiceFactory";
+
+export class DefaultExecutionBinaryService implements ExecutionBinaryService {
+  constructor(
+    private readonly storage: BinaryStorage,
+    private readonly workflowId: WorkflowId,
+    private readonly runId: RunId,
+    private readonly now: () => Date,
+  ) {}
+
+  forNode(args: { nodeId: NodeId; activationId: NodeActivationId }): NodeBinaryAttachmentService {
+    return new DefaultNodeBinaryAttachmentService(
+      this.storage,
+      this.workflowId,
+      this.runId,
+      args.nodeId,
+      args.activationId,
+      this.now,
+    );
+  }
+
+  async openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined> {
+    return await this.storage.openReadStream(attachment.storageKey);
+  }
+}
+
+export { DefaultNodeBinaryAttachmentService } from "./DefaultNodeBinaryAttachmentServiceFactory";
+export { UnavailableBinaryStorage } from "./UnavailableBinaryStorage";

package/src/binaries/DefaultNodeBinaryAttachmentServiceFactory.ts

@@ -0,0 +1,120 @@
+import type { BinaryAttachment, BinaryPreviewKind, Item, NodeActivationId, NodeId, RunId, WorkflowId } from "../types";
+
+import type {
+  BinaryAttachmentCreateRequest,
+  BinaryStorage,
+  BinaryStorageReadResult,
+  NodeBinaryAttachmentService,
+} from "../types";
+
+export class DefaultNodeBinaryAttachmentService implements NodeBinaryAttachmentService {
+  constructor(
+    private readonly storage: BinaryStorage,
+    private readonly workflowId: WorkflowId,
+    private readonly runId: RunId,
+    private readonly nodeId: NodeId,
+    private readonly activationId: NodeActivationId,
+    private readonly now: () => Date,
+  ) {}
+
+  async attach(args: BinaryAttachmentCreateRequest): Promise<BinaryAttachment> {
+    const attachmentId = this.createAttachmentId();
+    const createdAt = this.now().toISOString();
+    const storageKey = this.createStorageKey(args, attachmentId);
+    const stored = await this.storage.write({
+      storageKey,
+      body: args.body,
+    });
+    return {
+      id: attachmentId,
+      storageKey: stored.storageKey,
+      mimeType: args.mimeType,
+      size: stored.size,
+      storageDriver: this.storage.driverName,
+      previewKind: args.previewKind ?? this.resolvePreviewKind(args.mimeType),
+      createdAt,
+      runId: this.runId,
+      workflowId: this.workflowId,
+      nodeId: this.nodeId,
+      activationId: this.activationId,
+      filename: args.filename,
+      sha256: stored.sha256,
+    };
+  }
+
+  withAttachment<TJson>(item: Item<TJson>, name: string, attachment: BinaryAttachment): Item<TJson> {
+    return {
+      ...item,
+      binary: {
+        ...(item.binary ?? {}),
+        [name]: attachment,
+      },
+    };
+  }
+
+  forNode(args: { nodeId: NodeId; activationId: NodeActivationId }): NodeBinaryAttachmentService {
+    return new DefaultNodeBinaryAttachmentService(
+      this.storage,
+      this.workflowId,
+      this.runId,
+      args.nodeId,
+      args.activationId,
+      this.now,
+    );
+  }
+
+  async openReadStream(attachment: BinaryAttachment): Promise<BinaryStorageReadResult | undefined> {
+    return await this.storage.openReadStream(attachment.storageKey);
+  }
+
+  private createAttachmentId(): string {
+    return DefaultNodeBinaryAttachmentService.createAttachmentIdValue(`${this.activationId}-${this.now().getTime()}`);
+  }
+
+  private static createAttachmentIdValue(fallbackValue: string): string {
+    const cryptoObject = globalThis.crypto;
+    if (cryptoObject && typeof cryptoObject.randomUUID === "function") {
+      return cryptoObject.randomUUID();
+    }
+    return fallbackValue;
+  }
+
+  private createStorageKey(args: BinaryAttachmentCreateRequest, attachmentId: string): string {
+    const safeName = this.sanitizeSegment(args.name);
+    const safeFilename = this.sanitizeFilename(args.filename);
+    const filenameSuffix = safeFilename ? `-${safeFilename}` : "";
+    return `${this.sanitizeSegment(this.workflowId)}/${this.sanitizeSegment(this.runId)}/${this.sanitizeSegment(this.nodeId)}/${this.sanitizeSegment(this.activationId)}/${attachmentId}-${safeName}${filenameSuffix}`;
+  }
+
+  private sanitizeSegment(value: string): string {
+    const normalized = value.trim();
+    if (!normalized) {
+      return "item";
+    }
+    return normalized.replace(/[^a-zA-Z0-9._-]+/g, "_");
+  }
+
+  private sanitizeFilename(value: string | undefined): string | undefined {
+    if (!value) {
+      return undefined;
+    }
+    const normalized = value.trim().split("/").at(-1)?.split("\\").at(-1) ?? value.trim();
+    if (!normalized) {
+      return undefined;
+    }
+    return normalized.replace(/[^a-zA-Z0-9._-]+/g, "_");
+  }
+
+  private resolvePreviewKind(mimeType: string): BinaryPreviewKind {
+    if (mimeType.startsWith("image/")) {
+      return "image";
+    }
+    if (mimeType.startsWith("audio/")) {
+      return "audio";
+    }
+    if (mimeType.startsWith("video/")) {
+      return "video";
+    }
+    return "download";
+  }
+}

package/src/binaries/UnavailableBinaryStorage.ts

@@ -0,0 +1,19 @@
+import type { BinaryStorage } from "../types";
+
+export class UnavailableBinaryStorage implements BinaryStorage {
+  readonly driverName = "unavailable";
+
+  async write(): Promise<never> {
+    throw new Error("Binary storage is not configured for this runtime.");
+  }
+
+  async openReadStream(): Promise<undefined> {
+    return undefined;
+  }
+
+  async stat(): Promise<{ exists: false }> {
+    return { exists: false };
+  }
+
+  async delete(): Promise<void> {}
+}

package/src/binaries/index.ts

@@ -0,0 +1,2 @@
+export { DefaultExecutionBinaryService, UnavailableBinaryStorage } from "./DefaultExecutionBinaryServiceFactory";
+export { DefaultNodeBinaryAttachmentService } from "./DefaultNodeBinaryAttachmentServiceFactory";

package/src/bootstrap/index.ts

@@ -0,0 +1,46 @@
+/** Composition-root engine graph and advanced runtime wiring. Not part of the main `@codemation/core` barrel. */
+export { Engine } from "../orchestration/Engine";
+export { EngineFactory, type EngineCompositionDeps } from "../runtime/EngineFactory";
+export {
+  EngineRuntimeRegistrar,
+  type EngineRuntimeRegistrationOptions,
+  type TriggerRuntimeDiagnosticsProvider,
+  type WebhookTriggerMatcherProvider,
+} from "./runtime";
+export {
+  ConfigDrivenOffloadPolicy,
+  DefaultAsyncSleeper,
+  DefaultDrivingScheduler,
+  HintOnlyOffloadPolicy,
+  InProcessRetryRunner,
+  InlineDrivingScheduler,
+  LocalOnlyScheduler,
+  NodeInstanceFactory,
+  NodeExecutor,
+  type AsyncSleeper,
+} from "../execution";
+export {
+  EngineWorkflowRunnerService,
+  InMemoryLiveWorkflowRepository,
+  RunIntentService,
+  WorkflowRepositoryWebhookTriggerMatcher,
+} from "../runtime";
+export { DefaultExecutionBinaryService, UnavailableBinaryStorage } from "../binaries";
+export { DefaultExecutionContextFactory, CredentialResolverFactory } from "../execution";
+export {
+  InMemoryBinaryStorage,
+  InMemoryRunDataFactory,
+  InMemoryWorkflowExecutionRepository,
+  RunSummaryMapper,
+} from "../runStorage";
+export {
+  ENGINE_EXECUTION_LIMITS_DEFAULTS,
+  EngineExecutionLimitsPolicy,
+  EngineExecutionLimitsPolicyFactory,
+  RunPolicySnapshotFactory,
+  RunTerminalPersistenceCoordinator,
+  WorkflowPolicyErrorServices,
+  WorkflowStoragePolicyEvaluator,
+  type EngineExecutionLimitsPolicyConfig,
+} from "../policies";
+export { MissingRuntimeTriggerToken, PersistedWorkflowTokenRegistry } from "../workflowSnapshots";

package/src/bootstrap/runtime/EngineRuntimeRegistrar.ts

@@ -0,0 +1,180 @@
+import { instanceCachingFactory, type DependencyContainer } from "../../di";
+import { CoreTokens } from "../../di";
+import { EngineExecutionLimitsPolicyFactory } from "../../policies/executionLimits/EngineExecutionLimitsPolicyFactory";
+import {
+  DefaultAsyncSleeper,
+  InProcessRetryRunnerFactory,
+  NodeExecutor,
+  NodeExecutorFactory,
+  NodeInstanceFactoryFactory,
+} from "../../execution";
+import {
+  EngineFactory,
+  EngineWorkflowRunnerServiceFactory,
+  RunIntentServiceFactory,
+  RunIntentService,
+  WorkflowRepositoryWebhookTriggerMatcherFactory,
+} from "../../runtime";
+import { InlineDrivingScheduler } from "../../scheduler/InlineDrivingScheduler";
+import { InlineDrivingSchedulerFactory } from "../../scheduler/InlineDrivingSchedulerFactory";
+import { Engine } from "../../orchestration/Engine";
+import type { EngineRuntimeRegistrationOptions } from "./EngineRuntimeRegistration.types";
+import type { WebhookTriggerMatcherProvider } from "./EngineRuntimeRegistration.types";
+
+/**
+ * Container-first entry: call on a host/test container **after** workflow, run, node, and credential
+ * ports are registered. The registrar owns the default inline scheduler, engine binding,
+ * and intent-surface wiring so hosts only override the seams they actually replace.
+ */
+export class EngineRuntimeRegistrar {
+  register(container: DependencyContainer, options?: EngineRuntimeRegistrationOptions): void {
+    this.registerSupportFactories(container);
+    this.registerExecutionLimitsPolicy(container, options);
+    this.ensureWorkflowNodeInstanceFactory(container);
+    this.registerDefaultActivationScheduler(container);
+    this.registerEngine(container, options);
+    this.registerIntentServices(container);
+  }
+
+  private registerSupportFactories(container: DependencyContainer): void {
+    container.register(EngineExecutionLimitsPolicyFactory, { useClass: EngineExecutionLimitsPolicyFactory });
+    container.register(NodeInstanceFactoryFactory, { useClass: NodeInstanceFactoryFactory });
+    container.register(DefaultAsyncSleeper, { useClass: DefaultAsyncSleeper });
+    container.register(InProcessRetryRunnerFactory, { useClass: InProcessRetryRunnerFactory });
+    container.register(NodeExecutorFactory, { useClass: NodeExecutorFactory });
+    container.register(InlineDrivingSchedulerFactory, { useClass: InlineDrivingSchedulerFactory });
+    container.register(RunIntentServiceFactory, { useClass: RunIntentServiceFactory });
+    container.register(EngineWorkflowRunnerServiceFactory, {
+      useClass: EngineWorkflowRunnerServiceFactory,
+    });
+    container.register(WorkflowRepositoryWebhookTriggerMatcherFactory, {
+      useClass: WorkflowRepositoryWebhookTriggerMatcherFactory,
+    });
+  }
+
+  private registerExecutionLimitsPolicy(
+    container: DependencyContainer,
+    options: EngineRuntimeRegistrationOptions | undefined,
+  ): void {
+    if (container.isRegistered(CoreTokens.EngineExecutionLimitsPolicy, true)) {
+      return;
+    }
+    container.register(CoreTokens.EngineExecutionLimitsPolicy, {
+      useFactory: instanceCachingFactory((dependencyContainer) => {
+        const fromResolver = options?.resolveEngineExecutionLimits?.();
+        const merged = fromResolver ?? options?.engineExecutionLimits;
+        return dependencyContainer.resolve(EngineExecutionLimitsPolicyFactory).create(merged);
+      }),
+    });
+  }
+
+  private ensureWorkflowNodeInstanceFactory(container: DependencyContainer): void {
+    if (container.isRegistered(CoreTokens.WorkflowNodeInstanceFactory, true)) {
+      return;
+    }
+    container.register(CoreTokens.WorkflowNodeInstanceFactory, {
+      useFactory: instanceCachingFactory((dependencyContainer) => {
+        return dependencyContainer
+          .resolve(NodeInstanceFactoryFactory)
+          .create(dependencyContainer.resolve(CoreTokens.NodeResolver));
+      }),
+    });
+  }
+
+  private registerDefaultActivationScheduler(container: DependencyContainer): void {
+    if (container.isRegistered(CoreTokens.NodeActivationScheduler, true)) {
+      return;
+    }
+    container.register(NodeExecutor, {
+      useFactory: instanceCachingFactory((dependencyContainer) => {
+        const retryRunner = dependencyContainer
+          .resolve(InProcessRetryRunnerFactory)
+          .create(dependencyContainer.resolve(DefaultAsyncSleeper));
+        return dependencyContainer
+          .resolve(NodeExecutorFactory)
+          .create(dependencyContainer.resolve(CoreTokens.WorkflowNodeInstanceFactory), retryRunner);
+      }),
+    });
+    container.register(InlineDrivingScheduler, {
+      useFactory: instanceCachingFactory((dependencyContainer) => {
+        return dependencyContainer
+          .resolve(InlineDrivingSchedulerFactory)
+          .create(dependencyContainer.resolve(NodeExecutor));
+      }),
+    });
+    container.register(CoreTokens.NodeActivationScheduler, {
+      useFactory: instanceCachingFactory((dependencyContainer) => {
+        return dependencyContainer.resolve(InlineDrivingScheduler);
+      }),
+    });
+  }
+
+  private registerEngine(container: DependencyContainer, options: EngineRuntimeRegistrationOptions | undefined): void {
+    container.register(EngineFactory, { useClass: EngineFactory });
+    const matcherProvider = this.resolveMatcherProvider(options);
+    container.register(Engine, {
+      useFactory: instanceCachingFactory((dependencyContainer) => {
+        const liveWorkflowRepository = dependencyContainer.resolve(CoreTokens.LiveWorkflowRepository);
+        const nodeResolver = dependencyContainer.resolve(CoreTokens.NodeResolver);
+        const tokenRegistryLike = dependencyContainer.resolve(CoreTokens.PersistedWorkflowTokenRegistry);
+        const workflowActivationPolicy = dependencyContainer.resolve(CoreTokens.WorkflowActivationPolicy);
+        const webhookTriggerMatcher = matcherProvider.createMatcher(dependencyContainer);
+        const workflowNodeInstanceFactory = dependencyContainer.resolve(CoreTokens.WorkflowNodeInstanceFactory);
+        const triggerRuntimeDiagnostics = options?.triggerRuntimeDiagnosticsProvider?.create(dependencyContainer);
+        return dependencyContainer.resolve(EngineFactory).create({
+          credentialSessions: dependencyContainer.resolve(CoreTokens.CredentialSessionService),
+          liveWorkflowRepository,
+          workflowRepository: dependencyContainer.resolve(CoreTokens.WorkflowRepository),
+          workflowActivationPolicy,
+          nodeResolver,
+          triggerSetupStateRepository: dependencyContainer.resolve(CoreTokens.TriggerSetupStateRepository),
+          webhookTriggerMatcher,
+          runIdFactory: dependencyContainer.resolve(CoreTokens.RunIdFactory),
+          activationIdFactory: dependencyContainer.resolve(CoreTokens.ActivationIdFactory),
+          workflowExecutionRepository: dependencyContainer.resolve(CoreTokens.WorkflowExecutionRepository),
+          activationScheduler: dependencyContainer.resolve(CoreTokens.NodeActivationScheduler),
+          runDataFactory: dependencyContainer.resolve(CoreTokens.RunDataFactory),
+          executionContextFactory: dependencyContainer.resolve(CoreTokens.ExecutionContextFactory),
+          eventBus: dependencyContainer.resolve(CoreTokens.RunEventBus),
+          tokenRegistry: tokenRegistryLike,
+          workflowNodeInstanceFactory,
+          executionLimitsPolicy: dependencyContainer.resolve(CoreTokens.EngineExecutionLimitsPolicy),
+          triggerRuntimeDiagnostics,
+        });
+      }),
+    });
+  }
+
+  private registerIntentServices(container: DependencyContainer): void {
+    container.register(RunIntentService, {
+      useFactory: instanceCachingFactory((dependencyContainer) => {
+        return dependencyContainer
+          .resolve(RunIntentServiceFactory)
+          .create(dependencyContainer.resolve(Engine), dependencyContainer.resolve(CoreTokens.WorkflowRepository));
+      }),
+    });
+    container.register(CoreTokens.WorkflowRunnerService, {
+      useFactory: instanceCachingFactory((dependencyContainer) => {
+        return dependencyContainer
+          .resolve(EngineWorkflowRunnerServiceFactory)
+          .create(dependencyContainer.resolve(Engine), dependencyContainer.resolve(CoreTokens.WorkflowRepository));
+      }),
+    });
+  }
+
+  private resolveMatcherProvider(options: EngineRuntimeRegistrationOptions | undefined): WebhookTriggerMatcherProvider {
+    if (options?.webhookTriggerMatcherProvider) {
+      return options.webhookTriggerMatcherProvider;
+    }
+    return {
+      createMatcher: (container) =>
+        container
+          .resolve(WorkflowRepositoryWebhookTriggerMatcherFactory)
+          .create(
+            container.resolve(CoreTokens.WorkflowRepository),
+            container.resolve(CoreTokens.WorkflowActivationPolicy),
+            options?.webhookTriggerRoutingDiagnostics,
+          ),
+    };
+  }
+}

package/src/bootstrap/runtime/EngineRuntimeRegistration.types.ts

@@ -0,0 +1,43 @@
+import type { DependencyContainer } from "../../di";
+import type { WebhookTriggerMatcher } from "../../types";
+import type { WebhookTriggerRoutingDiagnostics } from "../../contracts/webhookTypes";
+import type { TriggerRuntimeDiagnostics } from "../../contracts/runtimeTypes";
+import type { EngineExecutionLimitsPolicyConfig } from "../../policies/executionLimits/EngineExecutionLimitsPolicy";
+
+/**
+ * Creates the webhook route matcher used by {@link import("../api/Engine").Engine}.
+ * Hosts may supply logging/diagnostics; tests often use the default factory without diagnostics.
+ */
+export interface WebhookTriggerMatcherProvider {
+  createMatcher(container: DependencyContainer): WebhookTriggerMatcher;
+}
+
+/**
+ * Supplies optional trigger-runtime logging (inactive workflow skips, activation sync).
+ */
+export interface TriggerRuntimeDiagnosticsProvider {
+  create(container: DependencyContainer): TriggerRuntimeDiagnostics | undefined;
+}
+
+export interface EngineRuntimeRegistrationOptions {
+  /**
+   * Static limits merged into the factory when the policy token is first resolved.
+   * Prefer {@link resolveEngineExecutionLimits} when limits can change after registration (e.g. host `useRuntimeConfig`).
+   */
+  engineExecutionLimits?: Partial<EngineExecutionLimitsPolicyConfig>;
+  /**
+   * Called when the limits policy is first resolved; overrides {@link engineExecutionLimits} when both are set.
+   * Use this for host wiring so `runtime.engineExecutionLimits` applied after `registerCoreInfrastructure` is honored.
+   */
+  resolveEngineExecutionLimits?: () => Partial<EngineExecutionLimitsPolicyConfig> | undefined;
+  /**
+   * When {@link webhookTriggerMatcherProvider} is omitted, the registrar builds
+   * {@link import("../../runtime/WorkflowRepositoryWebhookTriggerMatcher").WorkflowRepositoryWebhookTriggerMatcher}
+   * using this optional routing diagnostics surface.
+   */
+  webhookTriggerRoutingDiagnostics?: WebhookTriggerRoutingDiagnostics;
+  /** Overrides default webhook matcher construction (e.g. host-injected loggers). */
+  webhookTriggerMatcherProvider?: WebhookTriggerMatcherProvider;
+  /** Overrides default trigger diagnostics (undefined when omitted). */
+  triggerRuntimeDiagnosticsProvider?: TriggerRuntimeDiagnosticsProvider;
+}

package/src/bootstrap/runtime/index.ts

@@ -0,0 +1,6 @@
+export type {
+  EngineRuntimeRegistrationOptions,
+  TriggerRuntimeDiagnosticsProvider,
+  WebhookTriggerMatcherProvider,
+} from "./EngineRuntimeRegistration.types";
+export { EngineRuntimeRegistrar } from "./EngineRuntimeRegistrar";

package/src/browser.ts

@@ -0,0 +1,8 @@
+export { ConnectionNodeIdFactory } from "./workflow/definition/ConnectionNodeIdFactory";
+export * from "./contracts/credentialTypes";
+export * from "./contracts/runtimeTypes";
+export * from "./contracts/runFinishedAtFactory";
+export * from "./contracts/runTypes";
+export * from "./contracts/webhookTypes";
+export * from "./contracts/workflowTypes";
+export { ItemsInputNormalizer } from "./serialization/ItemsInputNormalizer";

package/src/contracts/Clock.ts

@@ -0,0 +1,10 @@
+/** Port for time; inject `SystemClock` in production and a fake/test clock in tests. */
+export interface Clock {
+  now(): Date;
+}
+
+export class SystemClock implements Clock {
+  now(): Date {
+    return new Date();
+  }
+}