@codemation/core 0.0.1

package/src/runtime/RunIntentService.ts

@@ -0,0 +1,175 @@
+import type {
+  CurrentStateExecutionRequest,
+  HttpMethod,
+  Items,
+  NodeId,
+  RunCurrentState,
+  RunExecutionOptions,
+  RunResult,
+  RunStopCondition,
+  WebhookInvocationMatch,
+  WebhookRunResult,
+  WebhookTriggerResolution,
+  WorkflowDefinition,
+  WorkflowRepository,
+} from "../types";
+
+import { Engine } from "../orchestration/Engine";
+
+export type StartWorkflowIntent = {
+  workflow: WorkflowDefinition;
+  startAt?: string;
+  items: Items;
+  parent?: CurrentStateExecutionRequest["parent"];
+  executionOptions?: RunExecutionOptions;
+  workflowSnapshot?: CurrentStateExecutionRequest["workflowSnapshot"];
+  mutableState?: CurrentStateExecutionRequest["mutableState"];
+  currentState?: RunCurrentState;
+  stopCondition?: RunStopCondition;
+  reset?: CurrentStateExecutionRequest["reset"];
+};
+
+export type RerunFromNodeIntent = {
+  workflow: WorkflowDefinition;
+  nodeId: NodeId;
+  currentState: RunCurrentState;
+  items?: Items;
+  parent?: CurrentStateExecutionRequest["parent"];
+  executionOptions?: RunExecutionOptions;
+  workflowSnapshot?: CurrentStateExecutionRequest["workflowSnapshot"];
+  mutableState?: CurrentStateExecutionRequest["mutableState"];
+};
+
+export type MatchedWebhookRunIntent = {
+  endpointPath: string;
+  method: HttpMethod;
+  requestItem: Items[number];
+};
+
+export type WebhookMatchRunIntent = {
+  match: WebhookInvocationMatch;
+  requestItem: Items[number];
+};
+
+export class RunIntentService {
+  constructor(
+    private readonly engine: Engine,
+    private readonly workflowRepository: WorkflowRepository,
+  ) {}
+
+  async startWorkflow(args: StartWorkflowIntent): Promise<RunResult> {
+    if (args.startAt && !args.currentState && !args.stopCondition && !args.reset) {
+      return await this.engine.runWorkflow(
+        args.workflow,
+        args.startAt,
+        args.items,
+        args.parent,
+        args.executionOptions,
+        {
+          workflowSnapshot: args.workflowSnapshot,
+          mutableState: args.mutableState,
+        },
+      );
+    }
+    return await this.engine.runWorkflowFromState({
+      workflow: args.workflow,
+      items: args.items,
+      parent: args.parent,
+      executionOptions: args.executionOptions,
+      workflowSnapshot: args.workflowSnapshot,
+      mutableState: args.mutableState,
+      currentState: args.currentState,
+      stopCondition: args.stopCondition ?? { kind: "workflowCompleted" },
+      reset: args.reset,
+    });
+  }
+
+  async rerunFromNode(args: RerunFromNodeIntent): Promise<RunResult> {
+    if (args.items) {
+      return await this.engine.runWorkflow(args.workflow, args.nodeId, args.items, args.parent, args.executionOptions, {
+        workflowSnapshot: args.workflowSnapshot,
+        mutableState: args.mutableState,
+      });
+    }
+    return await this.engine.runWorkflowFromState({
+      workflow: args.workflow,
+      parent: args.parent,
+      executionOptions: args.executionOptions,
+      workflowSnapshot: args.workflowSnapshot,
+      mutableState: args.mutableState,
+      currentState: args.currentState,
+      stopCondition: { kind: "workflowCompleted" },
+      reset: { clearFromNodeId: args.nodeId },
+    });
+  }
+
+  resolveWebhookTrigger(args: { endpointPath: string; method: HttpMethod }): WebhookTriggerResolution {
+    return this.engine.resolveWebhookTrigger(args);
+  }
+
+  async runMatchedWebhook(args: MatchedWebhookRunIntent): Promise<WebhookRunResult> {
+    const resolution = this.resolveWebhookTrigger(args);
+    if (resolution.status === "notFound") {
+      throw new Error("Unknown webhook endpoint");
+    }
+    if (resolution.status === "methodNotAllowed") {
+      throw new Error("Method not allowed");
+    }
+    return await this.runWebhookMatch({
+      match: resolution.match,
+      requestItem: args.requestItem,
+    });
+  }
+
+  async runWebhookMatch(args: WebhookMatchRunIntent): Promise<WebhookRunResult> {
+    const workflow = this.workflowRepository.get(args.match.workflowId);
+    if (!workflow) {
+      throw new Error(`Unknown workflowId: ${args.match.workflowId}`);
+    }
+    const scheduled = await this.engine.runWorkflow(
+      workflow,
+      args.match.nodeId,
+      [args.requestItem],
+      undefined,
+      this.createWebhookExecutionOptions(),
+    );
+    if (scheduled.status === "failed") {
+      throw new Error(scheduled.error.message);
+    }
+    if (scheduled.status === "completed") {
+      return {
+        runId: scheduled.runId,
+        workflowId: scheduled.workflowId,
+        startedAt: scheduled.startedAt,
+        runStatus: "completed",
+        response: scheduled.outputs,
+      };
+    }
+    return await Promise.race([
+      this.engine.waitForWebhookResponse(scheduled.runId),
+      this.engine.waitForCompletion(scheduled.runId).then((completed) => {
+        if (completed.status === "failed") {
+          throw new Error(completed.error.message);
+        }
+        return {
+          runId: completed.runId,
+          workflowId: completed.workflowId,
+          startedAt: completed.startedAt,
+          runStatus: "completed" as const,
+          response: completed.outputs,
+        } satisfies WebhookRunResult;
+      }),
+    ]);
+  }
+
+  /**
+   * Webhook-triggered runs always force inline execution first.
+   * This is the highest-precedence scheduler override: it wins over node hints and container defaults.
+   */
+  private createWebhookExecutionOptions(): RunExecutionOptions {
+    return {
+      localOnly: true,
+      webhook: true,
+    };
+  }
+}

package/src/runtime/RunIntentServiceFactory.ts

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

package/src/runtime/WorkflowRepositoryWebhookTriggerMatcher.ts

@@ -0,0 +1,144 @@
+import type {
+  HttpMethod,
+  NodeDefinition,
+  NodeId,
+  TriggerNodeConfig,
+  WebhookInvocationMatch,
+  WebhookTriggerMatcher,
+  WebhookTriggerRoutingDiagnostics,
+  WorkflowActivationPolicy,
+  WorkflowDefinition,
+  WorkflowId,
+  WorkflowRepository,
+} from "../types";
+
+/**
+ * Resolves webhook HTTP routes from the live workflow repository (no trigger setup / registration).
+ * Maintains an in-memory index keyed by user-defined endpoint path for O(1) lookups after reload.
+ */
+export class WorkflowRepositoryWebhookTriggerMatcher implements WebhookTriggerMatcher {
+  private readonly routeByPath = new Map<string, WebhookInvocationMatch>();
+  private engineRoutesActive = false;
+
+  constructor(
+    private readonly workflowRepository: WorkflowRepository,
+    private readonly workflowActivationPolicy: WorkflowActivationPolicy,
+    private readonly diagnostics?: WebhookTriggerRoutingDiagnostics,
+  ) {}
+
+  onEngineWorkflowsLoaded(): void {
+    this.engineRoutesActive = true;
+    this.rebuildRouteIndex();
+  }
+
+  onEngineStopped(): void {
+    this.engineRoutesActive = false;
+    this.routeByPath.clear();
+  }
+
+  reloadWebhookRoutes(): void {
+    if (!this.engineRoutesActive) {
+      return;
+    }
+    this.rebuildRouteIndex();
+  }
+
+  lookup(endpointPath: string): WebhookInvocationMatch | undefined {
+    if (!this.engineRoutesActive) {
+      return undefined;
+    }
+    const normalized = this.normalizeEndpointPath(endpointPath);
+    return this.routeByPath.get(normalized);
+  }
+
+  match(args: { endpointPath: string; method: HttpMethod }): WebhookInvocationMatch | undefined {
+    const entry = this.lookup(args.endpointPath);
+    if (!entry) {
+      return undefined;
+    }
+    return entry.methods.includes(args.method) ? entry : undefined;
+  }
+
+  private rebuildRouteIndex(): void {
+    this.routeByPath.clear();
+    for (const workflow of this.workflowRepository.list()) {
+      if (!this.workflowActivationPolicy.isActive(workflow.id)) {
+        const triggerCount = workflow.nodes.filter((n) => n.kind === "trigger").length;
+        if (triggerCount > 0) {
+          const paths = this.collectWebhookEndpointPaths(workflow);
+          if (paths.length > 0) {
+            this.diagnostics?.info?.(
+              `Workflow "${workflow.name}" (${workflow.id}) is inactive; webhook routes not registered: ${paths.map((p) => `"${p}"`).join(", ")}`,
+            );
+          } else {
+            this.diagnostics?.info?.(
+              `Workflow "${workflow.name}" (${workflow.id}) is inactive; no repository webhook routes for its triggers (other trigger kinds are unchanged).`,
+            );
+          }
+        }
+        continue;
+      }
+      for (const def of workflow.nodes) {
+        const match = this.tryMatchFromTriggerNode(workflow, def);
+        if (!match) {
+          continue;
+        }
+        const key = this.normalizeEndpointPath(match.endpointPath);
+        const existing = this.routeByPath.get(key);
+        if (existing) {
+          this.diagnostics?.warn(
+            `Duplicate webhook endpoint path "${key}" (workflows "${existing.workflowId}" and "${match.workflowId}"); using "${match.workflowId}".`,
+          );
+        }
+        this.routeByPath.set(key, match);
+      }
+    }
+  }
+
+  private collectWebhookEndpointPaths(workflow: WorkflowDefinition): string[] {
+    const paths: string[] = [];
+    for (const def of workflow.nodes) {
+      if (def.kind !== "trigger") {
+        continue;
+      }
+      const match = this.tryMatchFromTriggerNode(workflow, def);
+      if (match) {
+        paths.push(match.endpointPath);
+      }
+    }
+    return paths;
+  }
+
+  private tryMatchFromTriggerNode(
+    workflow: WorkflowDefinition,
+    def: NodeDefinition,
+  ): WebhookInvocationMatch | undefined {
+    if (def.kind !== "trigger") {
+      return undefined;
+    }
+    const config = def.config as TriggerNodeConfig & {
+      endpointKey?: unknown;
+      methods?: unknown;
+      parseJsonBody?: (body: unknown) => unknown;
+    };
+    if (typeof config.endpointKey !== "string" || config.endpointKey.length === 0) {
+      return undefined;
+    }
+    if (!Array.isArray(config.methods) || config.methods.length === 0) {
+      return undefined;
+    }
+    const methods = config.methods as HttpMethod[];
+    const parseJsonBody = typeof config.parseJsonBody === "function" ? config.parseJsonBody.bind(config) : undefined;
+    return {
+      endpointPath: config.endpointKey,
+      workflowId: workflow.id as WorkflowId,
+      nodeId: def.id as NodeId,
+      methods: [...methods],
+      parseJsonBody,
+    };
+  }
+
+  private normalizeEndpointPath(endpointPath: string): string {
+    return endpointPath.trim();
+  }
+}

package/src/runtime/WorkflowRepositoryWebhookTriggerMatcherFactory.ts

@@ -0,0 +1,13 @@
+import type { WebhookTriggerRoutingDiagnostics, WorkflowActivationPolicy, WorkflowRepository } from "../types";
+
+import { WorkflowRepositoryWebhookTriggerMatcher } from "./WorkflowRepositoryWebhookTriggerMatcher";
+
+export class WorkflowRepositoryWebhookTriggerMatcherFactory {
+  create(
+    workflowRepository: WorkflowRepository,
+    workflowActivationPolicy: WorkflowActivationPolicy,
+    diagnostics?: WebhookTriggerRoutingDiagnostics,
+  ): WorkflowRepositoryWebhookTriggerMatcher {
+    return new WorkflowRepositoryWebhookTriggerMatcher(workflowRepository, workflowActivationPolicy, diagnostics);
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,9 @@
+export { EngineFactory, type EngineCompositionDeps } from "./EngineFactory";
+export { EngineWorkflowRunnerService } from "./EngineWorkflowRunnerService";
+export { EngineWorkflowRunnerServiceFactory } from "./EngineWorkflowRunnerServiceFactory";
+export { InMemoryLiveWorkflowRepository } from "./InMemoryLiveWorkflowRepository";
+export { RunIntentService } from "./RunIntentService";
+export { RunIntentServiceFactory } from "./RunIntentServiceFactory";
+export { WorkflowRepositoryWebhookTriggerMatcher } from "./WorkflowRepositoryWebhookTriggerMatcher";
+export { WorkflowRepositoryWebhookTriggerMatcherFactory } from "./WorkflowRepositoryWebhookTriggerMatcherFactory";
+export { Engine, EngineWaiters, TriggerRuntimeService } from "../orchestration";

package/src/runtime-types/InjectableRuntimeDecoratorComposerRegistry.ts

@@ -0,0 +1,25 @@
+import { injectable } from "../di";
+
+import { PersistedRuntimeTypeMetadataStore } from "./PersistedRuntimeTypeMetadataStoreRegistry";
+import type {
+  DecoratedRuntimeType,
+  PersistedRuntimeTypeDecoratorOptions,
+  PersistedRuntimeTypeKind,
+} from "./persistedRuntimeTypeModelRegistry";
+
+/**
+ * Applies both tsyringe injectability and persisted runtime metadata in one decorator.
+ * This keeps runtime-type decorators thin while still recording enough data for snapshot hydration.
+ */
+export class InjectableRuntimeDecoratorComposer {
+  static compose(
+    kind: PersistedRuntimeTypeKind,
+    options: PersistedRuntimeTypeDecoratorOptions,
+    decoratorFileUrl: string,
+  ): ClassDecorator {
+    return (target) => {
+      injectable()(target as never);
+      PersistedRuntimeTypeMetadataStore.define(target as DecoratedRuntimeType, kind, options, decoratorFileUrl);
+    };
+  }
+}

package/src/runtime-types/PersistedRuntimeTypeMetadataStoreRegistry.ts

@@ -0,0 +1,46 @@
+import {
+  PersistedRuntimeTypeDecoratorDefaults,
+  persistedRuntimeTypeMetadataKey,
+  type DecoratedRuntimeType,
+  type PersistedRuntimeTypeDecoratorOptions,
+  type PersistedRuntimeTypeKind,
+  type PersistedRuntimeTypeMetadata,
+} from "./persistedRuntimeTypeModelRegistry";
+import { PersistedRuntimeTypeNameResolver } from "./PersistedRuntimeTypeNameResolver";
+import { StackTraceCallSitePathResolver } from "./StackTraceCallSitePathResolver";
+
+/**
+ * Defines and retrieves persisted runtime metadata on decorated classes.
+ * The metadata is attached as a non-enumerable property so runtime objects stay serializable.
+ */
+export class PersistedRuntimeTypeMetadataStore {
+  static define(
+    target: DecoratedRuntimeType,
+    kind: PersistedRuntimeTypeKind,
+    options: PersistedRuntimeTypeDecoratorOptions,
+    decoratorFileUrl: string,
+  ): void {
+    const normalizedOptions = PersistedRuntimeTypeDecoratorDefaults.apply(options);
+    const metadata: PersistedRuntimeTypeMetadata = {
+      persistedName: PersistedRuntimeTypeNameResolver.resolve(target, normalizedOptions.name),
+      kind,
+      packageName: normalizedOptions.packageName ?? PersistedRuntimeTypeDecoratorDefaults.appPackageName,
+      sourceHint: normalizedOptions.moduleUrl ?? StackTraceCallSitePathResolver.resolve(decoratorFileUrl),
+    };
+    Object.defineProperty(target, persistedRuntimeTypeMetadataKey, {
+      configurable: false,
+      enumerable: false,
+      writable: false,
+      value: metadata,
+    });
+  }
+
+  static get(target: unknown): PersistedRuntimeTypeMetadata | undefined {
+    if (!target || (typeof target !== "function" && typeof target !== "object")) {
+      return undefined;
+    }
+    return (target as Record<PropertyKey, unknown>)[persistedRuntimeTypeMetadataKey] as
+      | PersistedRuntimeTypeMetadata
+      | undefined;
+  }
+}

package/src/runtime-types/PersistedRuntimeTypeNameResolver.ts

@@ -0,0 +1,14 @@
+import type { DecoratedRuntimeType } from "./persistedRuntimeTypeModelRegistry";
+
+/** Resolves the persisted type name from either an explicit override or the class name itself. */
+export class PersistedRuntimeTypeNameResolver {
+  static resolve(target: DecoratedRuntimeType, override: string | undefined): string {
+    const resolved = override ?? target.name;
+    if (!resolved) {
+      throw new Error(
+        "Persisted runtime token metadata requires a named class or an explicit decorator name override.",
+      );
+    }
+    return resolved;
+  }
+}

package/src/runtime-types/StackTraceCallSitePathResolver.ts

@@ -0,0 +1,25 @@
+export class StackTraceCallSitePathResolver {
+  static resolve(decoratorFileUrl: string): string | undefined {
+    const stack = new Error().stack ?? "";
+    for (const line of stack.split("\n")) {
+      const candidate = this.extractPath(line.trim());
+      if (!candidate) {
+        continue;
+      }
+      if (candidate === decoratorFileUrl || candidate.includes("runtimeTypeDecorators")) {
+        continue;
+      }
+      return candidate;
+    }
+    return undefined;
+  }
+
+  private static extractPath(line: string): string | undefined {
+    const fileUrlMatch = line.match(/file:\/\/[^\s)]+/);
+    if (fileUrlMatch) return fileUrlMatch[0];
+    const parenMatch = line.match(/\((\/[^)]+)\)/);
+    if (parenMatch) return parenMatch[1];
+    const bareMatch = line.match(/at (\/[^\s]+)/);
+    return bareMatch?.[1];
+  }
+}

package/src/runtime-types/persistedRuntimeTypeModelRegistry.ts

@@ -0,0 +1,33 @@
+/** Shared metadata key used to attach persisted runtime-type information to decorated classes. */
+export const persistedRuntimeTypeMetadataKey = Symbol.for("codemation.core.persistedRuntimeTypeMetadata");
+
+export type DecoratedRuntimeType = Readonly<{ name?: string }> & object;
+
+/** Categories of runtime classes that can be discovered and rehydrated from persisted snapshots. */
+export type PersistedRuntimeTypeKind = "node" | "tool" | "chatModel";
+
+export interface PersistedRuntimeTypeDecoratorOptions {
+  readonly name?: string;
+  readonly packageName?: string;
+  readonly moduleUrl?: string;
+}
+
+/** Serialized metadata attached to a decorated runtime type. */
+export interface PersistedRuntimeTypeMetadata {
+  readonly persistedName: string;
+  readonly kind: PersistedRuntimeTypeKind;
+  readonly packageName: string;
+  readonly sourceHint?: string;
+}
+
+/** Normalizes decorator options so persistence metadata has stable defaults. */
+export class PersistedRuntimeTypeDecoratorDefaults {
+  static readonly appPackageName = "app";
+
+  static apply(options: PersistedRuntimeTypeDecoratorOptions): PersistedRuntimeTypeDecoratorOptions {
+    return {
+      ...options,
+      packageName: options.packageName ?? this.appPackageName,
+    };
+  }
+}

package/src/runtime-types/runtimeTypeDecorators.types.ts

@@ -0,0 +1,46 @@
+import type {
+  PersistedRuntimeTypeDecoratorOptions,
+  PersistedRuntimeTypeMetadata,
+} from "./persistedRuntimeTypeModelRegistry";
+
+import { InjectableRuntimeDecoratorComposer } from "./InjectableRuntimeDecoratorComposerRegistry";
+import { PersistedRuntimeTypeMetadataStore } from "./PersistedRuntimeTypeMetadataStoreRegistry";
+
+/**
+ * Public decorator entry points for runtime-discoverable classes.
+ *
+ * These exports intentionally stay as plain decorator factory functions because TypeScript's
+ * `@decorator()` syntax expects callable values rather than instance methods. The helpers below
+ * attach DI metadata and persisted-name metadata in one step so hosts can discover nodes, tools,
+ * and chat models without duplicating registration boilerplate.
+ */
+export type {
+  PersistedRuntimeTypeDecoratorOptions,
+  PersistedRuntimeTypeKind,
+  PersistedRuntimeTypeMetadata,
+} from "./persistedRuntimeTypeModelRegistry";
+
+/** Reads persisted runtime metadata from a decorated class or object. */
+export function getPersistedRuntimeTypeMetadata(target: unknown): PersistedRuntimeTypeMetadata | undefined {
+  return PersistedRuntimeTypeMetadataStore.get(target);
+}
+
+/** Marks a class as a persisted node runtime type and an injectable tsyringe service. */
+export function node(options: PersistedRuntimeTypeDecoratorOptions = {}): ClassDecorator {
+  return InjectableRuntimeDecoratorComposer.compose("node", options, import.meta.url);
+}
+
+/** Marks a class as a persisted tool runtime type and an injectable tsyringe service. */
+export function tool(options: PersistedRuntimeTypeDecoratorOptions = {}): ClassDecorator {
+  return InjectableRuntimeDecoratorComposer.compose("tool", options, import.meta.url);
+}
+
+/** Marks a class as a persisted chat-model runtime type and an injectable tsyringe service. */
+export function chatModel(options: PersistedRuntimeTypeDecoratorOptions = {}): ClassDecorator {
+  return InjectableRuntimeDecoratorComposer.compose("chatModel", options, import.meta.url);
+}
+
+export { InjectableRuntimeDecoratorComposer } from "./InjectableRuntimeDecoratorComposerRegistry";
+export { PersistedRuntimeTypeMetadataStore } from "./PersistedRuntimeTypeMetadataStoreRegistry";
+export { PersistedRuntimeTypeNameResolver } from "./PersistedRuntimeTypeNameResolver";
+export { StackTraceCallSitePathResolver } from "./StackTraceCallSitePathResolver";

package/src/scheduler/ConfigDrivenOffloadPolicy.ts

@@ -0,0 +1,28 @@
+import type {
+  ExecutionMode,
+  NodeConfigBase,
+  NodeId,
+  NodeOffloadPolicy,
+  NodeSchedulerDecision,
+  WorkflowId,
+} from "../types";
+export class ConfigDrivenOffloadPolicy implements NodeOffloadPolicy {
+  private readonly defaultMode: ExecutionMode;
+
+  constructor(defaultMode: ExecutionMode = "worker") {
+    this.defaultMode = defaultMode;
+  }
+
+  decide(args: { workflowId: WorkflowId; nodeId: NodeId; config: NodeConfigBase }): NodeSchedulerDecision {
+    const hint = args.config.execution?.hint;
+    const queue = args.config.execution?.queue;
+
+    if (hint === "local") return { mode: "local" };
+    if (hint === "worker") return { mode: "worker", queue };
+
+    // If a queue is specified, treat it as an implicit worker hint.
+    if (queue) return { mode: "worker", queue };
+
+    return { mode: this.defaultMode };
+  }
+}

package/src/scheduler/DefaultDrivingScheduler.ts

@@ -0,0 +1,100 @@
+import type {
+  NodeActivationContinuation,
+  NodeActivationReceipt,
+  NodeActivationRequest,
+  NodeActivationScheduler,
+  NodeExecutionRequest,
+  NodeExecutionScheduler,
+  NodeOffloadPolicy,
+} from "../types";
+import { InlineDrivingScheduler } from "./InlineDrivingScheduler";
+
+type SchedulerSelection = Readonly<{
+  mode: NodeActivationReceipt["mode"];
+  queue?: string;
+  decision: "runIntentOverride" | "nodePolicy" | "containerDefault";
+}>;
+
+export class DefaultDrivingScheduler implements NodeActivationScheduler {
+  constructor(
+    private readonly offloadPolicy: NodeOffloadPolicy,
+    private readonly workerScheduler: NodeExecutionScheduler,
+    private readonly inline: InlineDrivingScheduler,
+  ) {}
+
+  setContinuation(continuation: NodeActivationContinuation): void {
+    this.inline.setContinuation(continuation);
+  }
+
+  async enqueue(request: NodeActivationRequest): Promise<NodeActivationReceipt> {
+    const selection = await this.selectScheduler(request);
+    if (selection.mode === "worker") {
+      if (request.kind === "multi") {
+        throw new Error(`Multi-input node ${request.nodeId} cannot be scheduled to worker (insert local placement)`);
+      }
+
+      const workerRequest: NodeExecutionRequest = {
+        runId: request.runId,
+        activationId: request.activationId,
+        workflowId: request.workflowId,
+        nodeId: request.nodeId,
+        input: request.input,
+        parent: request.parent,
+        queue: selection.queue,
+        executionOptions: request.executionOptions,
+      };
+
+      const receipt = await this.workerScheduler.enqueue(workerRequest);
+      return { receiptId: receipt.receiptId, mode: "worker", queue: selection.queue };
+    }
+
+    return await this.enqueueInline(request);
+  }
+
+  notifyPendingStatePersisted(runId: string): void {
+    this.inline.notifyPendingStatePersisted(runId);
+  }
+
+  /**
+   * Scheduler precedence is explicit:
+   * 1. run-intent override (`executionOptions.localOnly`)
+   * 2. node-level execution hint / queue policy
+   * 3. container-default scheduler policy fallback
+   */
+  private async selectScheduler(request: NodeActivationRequest): Promise<SchedulerSelection> {
+    if (request.executionOptions?.localOnly) {
+      return {
+        mode: "local",
+        decision: "runIntentOverride",
+      };
+    }
+
+    const decision = this.offloadPolicy.decide({
+      workflowId: request.workflowId,
+      nodeId: request.nodeId,
+      config: request.ctx.config,
+    });
+    if (this.hasNodeSchedulingPreference(request)) {
+      return {
+        mode: decision.mode,
+        queue: decision.queue,
+        decision: "nodePolicy",
+      };
+    }
+
+    return {
+      mode: decision.mode,
+      queue: decision.queue,
+      decision: "containerDefault",
+    };
+  }
+
+  private hasNodeSchedulingPreference(request: NodeActivationRequest): boolean {
+    return request.ctx.config.execution?.hint !== undefined || request.ctx.config.execution?.queue !== undefined;
+  }
+
+  private async enqueueInline(request: NodeActivationRequest): Promise<NodeActivationReceipt> {
+    const receipt = await this.inline.enqueue(request);
+    return { ...receipt, mode: "local" };
+  }
+}