@makaio/framework 1.0.0-dev-1781023871421 → 1.0.0-dev-1781081952714

package/dist/index-YDfOv0GT.d.mts

@@ -0,0 +1,1133 @@
+import { r as ExtensionDiscovery } from "./extension-discovery-CkV_VRdJ.mjs";
+import { RegistrableBusNamespaceDefinition } from "@makaio/framework/core";
+import { BusTransport, IMakaioBus, SubjectTelemetryProjectorRegistry } from "@makaio/framework/bus";
+import { ExtensionConfigProvider, IWorkerNodeProvider, IWorkflowRunner, IWorkflowRunner as IWorkflowRunner$1, NormalizedWorkerNodeCapabilities, StationHandler, StepRunnerBusAuth, StepRunnerPlatformDefaults, TrayManifest, WorkerContributionManifest, WorkerNodeCapabilities, WorkerNodeDispatch, WorkerNodeHandle, WorkerNodeProvisionRequest, WorkerNodeRequirements, WorkflowDefinition, WorkflowRunResult, WorkflowRunResult as WorkflowRunResult$1, WorkflowRunnerRunOptions, WorkflowWorkerConfig, WorkflowWorkerSource, WorkflowZodSchemas } from "@makaio/framework/contracts";
+import { PostInstallHandler, StrategyDependencies } from "@makaio/framework/clients";
+import { DispatchingAuth, TransportAuth } from "@makaio/framework/node/transports";
+import { ContributionProcessor, ExtensionCoordinator, ExtensionRuntimeSurface, KernelExtensionContext, KernelMakaioExtension, RuntimeCapability, TransportProvider, WindowRegistry } from "@makaio/framework/kernel";
+import { Hono } from "hono";
+import { Server } from "node:http";
+
+//#region runtimes/node/src/hono-route-graph.d.ts
+/**
+ * Options for {@link createHonoRouteGraph}.
+ *
+ * Infrastructure routes handled by the stable facade rather than the
+ * rebuildable Hono app are configured here so that a full graph rebuild
+ * never accidentally removes them.
+ */
+interface HonoRouteGraphOptions {
+  /**
+   * Health check callback. When provided, the facade intercepts
+   * `GET /health` and returns a JSON response with the callback's return
+   * value. When absent, `/health` falls through to the active Hono app.
+   * @returns Any JSON-serialisable health snapshot.
+   */
+  health?: () => unknown;
+}
+/** Fetch facade for an atomically replaceable Hono route graph. */
+interface HonoRouteGraph {
+  /**
+   * Stable fetch function passed to the owning HTTP server.
+   *
+   * Before {@link markReady} it returns 503 without invoking Hono so the
+   * mutable matcher is not built while boot is still registering routes.
+   */
+  readonly fetch: Hono['fetch'];
+  /**
+   * Allow HTTP requests to reach the active Hono app.
+   */
+  markReady(): void;
+  /**
+   * Swap future requests to a fully constructed Hono app.
+   *
+   * Existing requests keep using the app captured at dispatch time; new
+   * requests observe the replacement immediately.
+   * @param nextApp - Fully registered Hono app to serve for future requests.
+   */
+  replaceApp(nextApp: Hono): void;
+}
+/**
+ * Create a stable HTTP-server fetch facade over an immutable-at-runtime Hono app.
+ *
+ * Hono route tables are mutable only until their matcher has handled a request.
+ * Composition roots that bind the TCP server before runtime boot finishes must
+ * keep early requests away from `app.fetch()`, then expose the app once all
+ * boot-time routes are mounted. Dynamic route changes should build a fresh
+ * Hono app off-path and call {@link HonoRouteGraph.replaceApp}.
+ *
+ * Infrastructure routes (`GET /health`, `GET /bus`) are handled by the stable
+ * facade so they survive graph rebuilds and are never accidentally removed.
+ * The `/bus` upgrade path returns 426 to signal that the endpoint requires a
+ * WebSocket upgrade, replacing the former `registerBusHttpEndpoint` helper.
+ * @param initialApp - Initial Hono app used after boot readiness.
+ * @param options - Optional facade-level route configuration.
+ * @returns Stable fetch facade plus readiness/replacement controls.
+ */
+declare function createHonoRouteGraph(initialApp: Hono, options?: HonoRouteGraphOptions): HonoRouteGraph;
+//#endregion
+//#region runtimes/node/src/http-route-contribution.d.ts
+/** The ordered phase in which an HTTP route contribution is mounted. */
+type HttpContributionPhase = 'extension' | 'static-fallback';
+/**
+ * A single contribution to the HTTP route graph.
+ *
+ * Contributions declare their routing phase so the builder can mount them in
+ * the correct order regardless of registration order.
+ */
+interface HttpRouteContribution {
+  /** Stable identifier for the contributing owner; used to remove by owner. */
+  readonly owner: string;
+  /** Phase determines mount order: `extension` before `static-fallback`. */
+  readonly phase: HttpContributionPhase;
+  /**
+   * Mount routes onto the provided Hono app.
+   * @param app - Fresh Hono app being assembled by the builder.
+   */
+  readonly mount: (app: Hono) => void;
+}
+//#endregion
+//#region runtimes/node/src/http-route-graph-builder.d.ts
+/**
+ * Manages a mutable set of {@link HttpRouteContribution}s and keeps the owning
+ * {@link HonoRouteGraph} up to date whenever contributions change.
+ */
+interface HttpRouteGraphBuilder {
+  /**
+   * Add a contribution and trigger a rebuild of the route graph.
+   * @param contribution - The contribution to register.
+   */
+  add(contribution: HttpRouteContribution): void;
+  /**
+   * Remove all contributions registered under the given owner and trigger a
+   * rebuild.  A no-op when the owner is not registered.
+   * @param owner - The owner identifier to remove.
+   */
+  remove(owner: string): void;
+  /**
+   * Assemble and return a fresh Hono app from the current contributions sorted
+   * by phase.
+   * @returns Newly constructed Hono app.
+   */
+  build(): Hono;
+  /** Snapshot of the current contributions in registration order. */
+  readonly contributions: ReadonlyArray<HttpRouteContribution>;
+}
+/**
+ * Create an {@link HttpRouteGraphBuilder} backed by an optional route graph.
+ *
+ * When `routeGraph` is provided, every {@link HttpRouteGraphBuilder.add} and
+ * {@link HttpRouteGraphBuilder.remove} call triggers
+ * {@link HonoRouteGraph.replaceApp} with a freshly assembled Hono app.
+ *
+ * When `routeGraph` is `undefined` (e.g. the Vite dev-server mode where the
+ * route graph lives in the Vite plugin), contributions accumulate without
+ * triggering a rebuild.
+ * @param routeGraph - Route graph to update on change, or `undefined` to
+ *   accumulate contributions without rebuilding.
+ * @returns Builder instance managing contributions and rebuilds.
+ */
+declare function createHttpRouteGraphBuilder(routeGraph: HonoRouteGraph | undefined): HttpRouteGraphBuilder;
+//#endregion
+//#region runtimes/node/src/framework-module-resolver.d.ts
+interface FrameworkModuleResolver {
+  readonly frameworkDistPath: string;
+  install(): void | Promise<void>;
+  uninstall(): void | Promise<void>;
+}
+/** Runtime package export value shapes used by `@makaio/framework`. */
+type FrameworkPackageExportValue = string | FrameworkPackageExportConditions;
+/** Runtime package exports map keyed by subpath (e.g. `./bus`). */
+type FrameworkPackageExports = Readonly<Record<string, FrameworkPackageExportValue>>;
+/** Conditional package export object. Runtime resolution ignores type-only conditions. */
+interface FrameworkPackageExportConditions {
+  readonly default?: unknown;
+  readonly import?: unknown;
+  readonly require?: unknown;
+  readonly types?: unknown;
+  readonly [condition: string]: unknown;
+}
+/**
+ * No-op resolver for dev mode or environments where workspace resolution
+ * already provides `@makaio/framework/*`.
+ */
+declare class NoopFrameworkModuleResolver implements FrameworkModuleResolver {
+  readonly frameworkDistPath = "";
+  install(): void;
+  uninstall(): void;
+}
+/**
+ * Node.js resolver for packaged hosts that ship an assembled `@makaio/framework`
+ * dist next to the app resources.
+ *
+ * Imports `registerHooks` from `node:module` lazily in {@link install} so this
+ * file can be loaded safely in Bun where that export does not exist.
+ */
+declare class NodeFrameworkModuleResolver implements FrameworkModuleResolver {
+  readonly frameworkDistPath: string;
+  private hooks;
+  private installPromise;
+  private installToken;
+  /**
+   * @param frameworkDistPath - Absolute path to the assembled framework dist.
+   */
+  constructor(frameworkDistPath: string);
+  install(): Promise<void>;
+  private installWithToken;
+  uninstall(): void;
+}
+/**
+ * Resolves a `@makaio/framework/*` subpath specifier to a filesystem path
+ * within the configured dist directory.
+ * @param frameworkDistPath - Absolute path to the assembled framework dist.
+ * @param specifier - Full import specifier (e.g. `@makaio/framework/bus`).
+ * @param packageExports - Optional preloaded package exports map. When omitted,
+ *   the map is read from the package.json next to `frameworkDistPath`.
+ * @returns Resolved filesystem path, or `undefined` if the specifier is not a framework subpath.
+ */
+declare function resolveFrameworkSpecifier(frameworkDistPath: string, specifier: string, packageExports?: FrameworkPackageExports): string | undefined;
+//#endregion
+//#region runtimes/node/src/create-static-mount.d.ts
+/**
+ * Options shared by {@link bridgeExtensionBrowserEntries} and
+ * {@link synthesizeBrowserOnlyPackages} for controlling static-file serving.
+ */
+interface BridgeBrowserOptions {
+  /**
+   * Factory for creating the static-serving mount callback.
+   *
+   * Injected for testability — production default uses `@hono/node-server/serve-static`
+   * synchronously and mounts the directory under `urlPrefix`.
+   * @param serveRoot - Absolute path to the directory containing the browser bundle.
+   * @param urlPrefix - URL prefix for the route (e.g., `/extensions/my-ext/browser`).
+   * @returns A mount callback compatible with {@link MakaioExtension.http.mount}.
+   */
+  readonly createMount?: (serveRoot: string, urlPrefix: string) => (app: unknown) => void;
+}
+//#endregion
+//#region runtimes/node/src/boot-phase.d.ts
+/** Shared helpers for runtime shutdown ordering. */
+/**
+ * Async or sync shutdown callback collected during runtime boot.
+ */
+type ShutdownStep = () => Promise<void> | void;
+//#endregion
+//#region runtimes/node/src/boot-extension-selection.d.ts
+/**
+ * Return host capability tokens for Node.js composition roots.
+ *
+ * This helper is intentionally called by Node surfaces before boot rather
+ * than from {@link buildRuntimeEnvironment}, so the platform token remains an
+ * explicit host policy and Bun/future runtimes do not inherit Node semantics.
+ * @param hostCapabilities - Host-declared capability facts.
+ * @returns Capability tokens with `'node'` present exactly once.
+ */
+declare function normalizeNodeHostCapabilities(hostCapabilities?: readonly HostCapabilityDeclaration[]): readonly HostCapabilityDeclaration[];
+/** Host capability input accepted by Node runtime composition roots. */
+type HostCapabilityDeclaration = string | RuntimeCapability;
+type RuntimeOwnershipPackageView = Pick<KernelMakaioExtension, 'name' | 'displayName' | 'version' | 'runtimeOwnership'>;
+/**
+ * Select framework core packages for the loaded descriptor-backed extensions.
+ *
+ * The framework session orchestrator is the default owner of
+ * `session.sendMessage`. It is omitted when a loaded extension declares
+ * `runtimeOwnership.sessionOrchestrator`, and boot fails if more than one
+ * loaded extension declares that ownership.
+ * @param loadedExtensionPackages - Descriptor-loaded executable extension packages.
+ * @returns Framework core packages for this boot.
+ */
+declare function selectFrameworkCorePackages(loadedExtensionPackages: ReadonlyArray<RuntimeOwnershipPackageView> | true): ReadonlyArray<KernelMakaioExtension>;
+//#endregion
+//#region runtimes/node/src/workflow-worker/worker-entry-resolver.d.ts
+/** Worker entry build mode. */
+type WorkflowWorkerEntryMode = 'source' | 'dist';
+/**
+ * Options for resolving the workflow worker entrypoint file path.
+ */
+interface WorkflowWorkerEntryResolverOptions {
+  /** Absolute path to the package root directory. */
+  readonly packageRoot: string;
+  /** Whether to resolve the source TypeScript entry or the built distribution entry. */
+  readonly mode: WorkflowWorkerEntryMode;
+}
+/**
+ * Resolve the absolute file path to the workflow worker entrypoint.
+ *
+ * In `source` mode, returns the TypeScript source path used during development
+ * (requires a loader like `tsx` or `ts-node` for direct execution).
+ * In `dist` mode, returns the compiled ESM bundle path used in production.
+ * @param options - Resolution options with package root and mode.
+ * @returns Absolute path to the workflow worker entrypoint file.
+ */
+declare function resolveWorkflowWorkerEntry(options: WorkflowWorkerEntryResolverOptions): string;
+//#endregion
+//#region runtimes/node/src/boot-types.d.ts
+/** Dev-mode map from npm package name to absolute workspace package directory. */
+type DevPortalMap = ReadonlyMap<string, string>;
+/**
+ * Public handle for the adapter subsystem service methods exposed during host
+ * coordinator wiring.
+ */
+interface AdapterSubsystemServiceHandle {
+  /**
+   * Process adapter contributions for one active extension package.
+   * @param packageName - Package that transitioned to active.
+   * @param pkg - Extension manifest.
+   * @param ctx - Per-extension context.
+   */
+  processAdapterContributions(packageName: string, pkg: KernelMakaioExtension, ctx: KernelExtensionContext): Promise<void>;
+  /**
+   * Stop adapter contributions for one stopped extension package.
+   * @param packageName - Package that stopped or was disabled.
+   */
+  stopAdapterContributions(packageName: string): Promise<void>;
+}
+/**
+ * Runtime boot configuration for the workflow-level runner.
+ *
+ * When omitted, the workflow engine uses its built-in runner default.
+ * Explicit `{ mode: 'in-process' }` installs the Node runtime's concrete
+ * in-process runner.
+ * Set `mode: 'piscina'` to dispatch each full workflow execution to a
+ * Piscina worker-thread pool running the workflow worker entry.
+ */
+type WorkflowRunnerBootOptions = {
+  /** Use the Node runtime's concrete in-process workflow runner. */readonly mode?: 'in-process';
+} | {
+  /** Dispatch full workflow executions to a Piscina worker-thread pool. */readonly mode: 'piscina'; /** Contribution manifest loaded inside isolated workers. */
+  readonly manifest?: WorkerContributionManifest; /** Explicit worker entry path. Overrides workerEntryMode resolution. */
+  readonly workerEntry?: string; /** Source/dist worker entry mode used when workerEntry is omitted. */
+  readonly workerEntryMode?: WorkflowWorkerEntryMode; /** Maximum concurrent worker threads. */
+  readonly maxConcurrency?: number; /** Idle timeout before worker threads are reaped. */
+  readonly idleTimeoutMs?: number;
+} | {
+  /**
+   * Delegate workflow executions to a product-owned WorkerNode dispatch seam.
+   *
+   * The dispatch function is supplied by the host composition root and
+   * typically wired to `workerPool.dispatch`. Framework code remains
+   * decoupled from any pool implementation details.
+   */
+  readonly mode: 'worker-node';
+  /**
+   * WorkerNode dispatch function injected by the host composition root.
+   *
+   * Called once per workflow execution with the full worker config and
+   * manifest. Product hosts may wire this to `workerPool.dispatch`.
+   * When omitted, the Node runtime dispatches through the framework
+   * `worker-node.dispatch` bus subject and requires a bus instance.
+   */
+  readonly dispatch?: WorkerNodeDispatch;
+  /**
+   * Contribution manifest forwarded to each dispatch call.
+   *
+   * When omitted, no explicit manifest is forwarded. Product hosts that
+   * resolve project-level manifests in the dispatch function can leave this
+   * empty so the dispatch layer can perform resolution.
+   */
+  readonly manifest?: WorkerContributionManifest;
+  /**
+   * Optional resource requirements forwarded to pool dispatch.
+   *
+   * When provided, the pool uses these to select a compatible provider.
+   * Omit to accept any available pool with no constraints.
+   */
+  readonly requirements?: WorkerNodeRequirements;
+};
+/**
+ * Bound address info passed to {@link BootMakaioRuntimeOptions.onTransportReady}.
+ */
+interface TransportReadyInfo {
+  /** Bound TCP port. */
+  port: number;
+  /** Bound host address (e.g. `'127.0.0.1'` or `'0.0.0.0'`). */
+  host: string;
+}
+/**
+ * Extension of {@link TransportProvider} that exposes an optional
+ * {@link DispatchingAuth} handle for E2E auth hot-swap.
+ *
+ * Both Node and Bun transport providers implement this interface so the core
+ * boot sequence can install E2E auth without depending on a concrete provider
+ * class.
+ */
+interface ServerTransportProvider extends TransportProvider {
+  /**
+   * The {@link DispatchingAuth} instance if the caller passed one.
+   *
+   * Exposed so boot can hot-swap E2E auth after machine identity becomes
+   * available. Returns `undefined` when auth was not provided or is not a
+   * {@link DispatchingAuth}.
+   */
+  readonly dispatchingAuth?: DispatchingAuth;
+}
+/**
+ * Boot-time configuration for the optional projected upstream telemetry transport.
+ */
+interface UpstreamTelemetryBootOptions {
+  /**
+   * Inner transport connected to the upstream collector.
+   *
+   * Raw application messages are never sent to it directly — only sanitized
+   * `subject-telemetry.fact` events are forwarded by the projection layer.
+   */
+  readonly transport: BusTransport;
+  /**
+   * Registry name for the projected transport.
+   *
+   * Defaults to `'upstream-telemetry'`. Must be unique within the bus
+   * transport registry.
+   */
+  readonly name?: string;
+  /**
+   * Optional sidecar projector registry for namespace-owned attribute extraction.
+   *
+   * When provided, sidecar projectors registered for a message's namespace and
+   * subject take precedence over schema-driven attribute projection inside the
+   * projected transport.
+   */
+  readonly projectorRegistry?: SubjectTelemetryProjectorRegistry;
+}
+/**
+ * Platform-agnostic boot options shared by all runtime platforms.
+ *
+ * The Node-specific {@link BootMakaioRuntimeOptions} adds `httpServer` on top
+ * of this base. Alternative platform boots (e.g. Bun) construct their own
+ * transport and pass it alongside these options to `bootMakaioRuntimeCore`.
+ */
+interface CoreBootOptions {
+  /**
+   * Optional route graph builder for dynamic HTTP route management.
+   *
+   * When provided, an {@link HttpContributionProcessor} is registered that
+   * adds/removes extension HTTP routes on enable/disable, triggering a
+   * Hono app rebuild via {@link HonoRouteGraph.replaceApp}. When absent
+   * (e.g. Vite dev mode), extension HTTP routes are not mounted by boot.
+   */
+  routeGraphBuilder?: HttpRouteGraphBuilder;
+  /**
+   * Pre-built auth strategy (HMAC, DispatchingAuth, or undefined for dev).
+   *
+   * When `undefined` the bus server runs with no authentication — safe only
+   * in dev mode (loopback-only binding).
+   */
+  auth?: TransportAuth;
+  /**
+   * Loopback transport registry name for in-process cross-client relay.
+   *
+   * Defaults to `'node'`.
+   */
+  loopbackName?: string;
+  /**
+   * Enable E2E auth hot-swap after machine identity loads.
+   *
+   * When `true` and `auth` is a {@link DispatchingAuth}, the E2E strategy is
+   * installed into the dispatching auth instance after machine identity
+   * becomes available. Set this when binding on all interfaces (LAN mode).
+   */
+  lanBind?: boolean;
+  /**
+   * Resolve a peer device's signing public key for E2E relay authentication.
+   *
+   * Required when `lanBind` is enabled — boot fails fast if missing. The
+   * resolver is invoked during E2E handshakes to verify the identity of a
+   * connecting peer. Returning `null` rejects the peer as unknown or revoked.
+   *
+   * Providing this at the composition root keeps the boot layer free of any
+   * host device-registry dependency.
+   * @param peerId - Device ID of the connecting peer.
+   * @returns CryptoKey for signature verification, or `null` for unknown/revoked peers.
+   */
+  peerSigningKeyResolver?: (peerId: string) => Promise<CryptoKey | null>;
+  /**
+   * Hosted surface category for extension gating.
+   *
+   * Defaults to `'headless'`. Interactive surfaces like Vite dev server or
+   * Electron should pass `'interactive'` so UI-bound extensions can load.
+   */
+  surface?: ExtensionRuntimeSurface;
+  /**
+   * Filesystem path to the framework central Drizzle migrations directory.
+   *
+   * Normal source builds omit this and use the package-local
+   * `@makaio/storage-migrations/drizzle` folder. Bundled hosts pass the copied
+   * runtime asset path explicitly because the original package directory may
+   * not exist in the deployed image.
+   */
+  readonly centralMigrationsDir?: string;
+  /**
+   * Host launcher command embedded into client wiring installed from warning actions.
+   *
+   * Defaults to `'makaio'`. Prefer `makaio.config.*` when a user/workspace
+   * needs a different launcher identity.
+   */
+  readonly launcherCommand?: string;
+  /**
+   * Enable the extension package-manager service.
+   *
+   * Defaults to `true` for interactive/dev hosts. Bundled cloud hosts can set
+   * this to `false` because their extension set is fixed at image build time
+   * and the Yarn package-management service is not part of the runtime surface.
+   */
+  readonly enablePackageManager?: boolean;
+  /**
+   * Called when the bus WebSocket transport is attached and accepting
+   * connections, before service boot begins.
+   *
+   * This is the earliest safe moment for external clients to connect to
+   * the bus. Composition roots use this to announce the bound address
+   * (e.g. `MAKAIO_PORT=<n>` on stdout) or to unblock dependent processes.
+   * @param info - Bound host and port from the server.
+   */
+  onTransportReady?: (info: TransportReadyInfo) => void;
+  /**
+   * Custom extension discovery strategy.
+   *
+   * When provided, replaces the default `FilesystemDescriptorDiscovery`
+   * instance. Use `ExplicitDescriptorDiscovery` to supply pre-scanned
+   * extension descriptors in tests or host-owned discovery flows.
+   */
+  discovery?: ExtensionDiscovery;
+  /**
+   * Framework version used for extension `makaio.framework` range gating.
+   *
+   * When omitted, the version is read from `@makaio/runtime-node`'s
+   * `package.json` at boot time. Pass an explicit value in tests or host
+   * builds where the package.json may not be on disk.
+   */
+  frameworkVersion?: string;
+  /**
+   * Capability facts declared by the host composition root.
+   *
+   * Passed to the coordinator as the host capability set, with object-form
+   * entries preserving concrete versions for versioned `requires` checks.
+   * Runtime tokens such as `'node'` must be included here by Node-based hosts;
+   * the boot layer no longer injects them automatically so that Bun and future
+   * platforms can declare their own tokens.
+   * @example
+   * ```ts
+   * ['node', 'workspace-host', { id: 'storage.drizzle', version: '1.2.0' }]
+   * ```
+   */
+  readonly hostCapabilities?: readonly HostCapabilityDeclaration[];
+  /**
+   * Host-owned bus namespace definitions registered during the core bus boot
+   * phase before any handlers, services, or remote clients can use them.
+   *
+   * Use this for surface-specific contracts owned outside runtime-node, such as
+   * desktop UI namespaces, without making the generic runtime depend on those
+   * packages.
+   */
+  readonly hostNamespaces?: readonly RegistrableBusNamespaceDefinition[];
+  /**
+   * Host-provided package config defaults keyed by package name.
+   *
+   * Merged with descriptor defaults before stored config is loaded. Prefer
+   * `makaio.config.*` for user/workspace runtime defaults; this seam remains
+   * for composition roots that need to inject process-local defaults.
+   */
+  readonly packageConfigDefaults?: ReadonlyMap<string, Readonly<Record<string, unknown>>>;
+  /**
+   * Host-provided handlers for client binary post-install descriptors.
+   *
+   * Client packages declare declarative `postInstall.kind` values; composition
+   * roots provide the concrete handler map here so `@makaio/runtime-node` stays free
+   * of host-specific post-install logic.
+   */
+  readonly clientBinaryPostInstallHandlers?: ReadonlyMap<string, PostInstallHandler>;
+  /**
+   * Workflow-level runner for dispatching full workflow executions.
+   *
+   * Omit to use the workflow engine's built-in default runner. Set to
+   * `{ mode: 'in-process' }` to install the Node runtime's concrete in-process
+   * runner, or `piscina` to dispatch each execution to a worker-thread pool
+   * that runs the workflow worker entry end-to-end.
+   */
+  readonly workflowRunner?: WorkflowRunnerBootOptions;
+  /**
+   * Runtime data home for config, database, machine identity, and installed
+   * extensions. Defaults to the `MAKAIO_HOME` environment override when set,
+   * otherwise `~/.makaio`.
+   */
+  readonly makaioHome?: string;
+  /**
+   * Host-provided fallback model-registry seed candidates.
+   *
+   * These are tried after the CDN cache source and before the runtime's
+   * boot-relative seed path. Desktop package surfaces use this to pass
+   * resource directories that are known only to the app shell, keeping
+   * runtime-node free of Electron/Electrobun globals while preserving CDN
+   * freshness whenever the network source is available.
+   */
+  readonly modelRegistryFallbackSeedPaths?: readonly string[];
+  /**
+   * Optional runtime module resolver for `@makaio/framework/*` subpath imports.
+   *
+   * When provided, installed before extension loading so published extensions
+   * resolve framework imports to the packaged dist. Not needed in dev mode
+   * where workspace resolution handles framework imports.
+   */
+  readonly frameworkModuleResolver?: FrameworkModuleResolver;
+  /**
+   * Host-provided `@makaio/framework` package root.
+   *
+   * Packaged hosts can pass the app-bundled framework package here so installed
+   * extensions and package-manager installs resolve framework imports to the
+   * same physical package instance as the host process.
+   */
+  readonly frameworkPackagePath?: string;
+  /**
+   * Host-provided managed-binary I/O implementation.
+   *
+   * The shared boot core only wires the seam through. Concrete hosts supply
+   * their own filesystem, network, archive, and subprocess implementation so
+   * Node, Bun, and future runtimes do not inherit Node-shaped I/O implicitly.
+   */
+  readonly clientBinaryStrategyDependencies?: StrategyDependencies;
+  /**
+   * Dev-mode workspace package map used to rewrite extension install specs to
+   * Yarn `portal:` ranges.
+   *
+   * When provided and non-empty, the package-manager service wraps its
+   * dependency resolver so that installs for known workspace packages link
+   * directly to local source directories instead of fetching from npm. This is
+   * the same `portal:` mechanism used for `frameworkPackagePath`, extended to
+   * the full set of extension packages available in the host workspace.
+   *
+   * Has no effect when `enablePackageManager` is `false`.
+   */
+  readonly devPortalPackages?: DevPortalMap;
+  /**
+   * Optional provider for persisted extension configuration and enablement state.
+   *
+   * When present, the coordinator consults this provider during {@link ExtensionCoordinator.startAll}
+   * and `ExtensionCoordinator.enableExtension` to load stored configuration and
+   * skip packages that were previously disabled. When absent, all extensions
+   * start enabled with default (Zod-schema) configuration only.
+   */
+  readonly extensionConfigProvider?: ExtensionConfigProvider;
+  /**
+   * Host-owned coordinator wiring invoked after framework processors are registered
+   * and before {@link ExtensionCoordinator.startAll}.
+   *
+   * Concrete hosts use this seam for contribution processors and bus services
+   * that must observe active extension contributions without importing
+   * host-owned packages into the framework boot layer.
+   * @param context - Coordinator setup context.
+   * @returns Optional cleanup callbacks collected into runtime shutdown.
+   */
+  readonly configureCoordinator?: (context: BootCoordinatorSetupContext) => void | ShutdownStep | readonly ShutdownStep[];
+  /**
+   * Optional projected upstream telemetry transport.
+   *
+   * Boot wraps this transport with a projector that only sends
+   * `subject-telemetry.fact` events upstream. The raw transport is never
+   * registered directly on the bus.
+   */
+  readonly upstreamTelemetry?: UpstreamTelemetryBootOptions;
+  /**
+   * Static mount factory for extension browser bundles.
+   *
+   * Node hosts default to `@hono/node-server/serve-static`; Bun hosts pass
+   * their Bun-native `hono/bun` implementation through this seam.
+   *
+   * When omitted, the platform-default factory is used (Node: `@hono/node-server/serve-static`).
+   */
+  readonly createMount?: BridgeBrowserOptions['createMount'];
+}
+/** Context passed to host-owned coordinator setup. */
+interface BootCoordinatorSetupContext {
+  /** Runtime bus. */
+  readonly bus: IMakaioBus;
+  /** Extension coordinator being configured before startup. */
+  readonly coordinator: ExtensionCoordinator;
+  /** Register an awaited contribution processor. */
+  readonly registerContributionProcessor: (processor: ContributionProcessor) => void;
+  /** Read the active adapter subsystem service when it exists. */
+  readonly getAdapterSubsystemService: () => AdapterSubsystemServiceHandle | undefined;
+}
+/**
+ * Options for `bootMakaioRuntime` (Node.js platform).
+ *
+ * Extends the platform-agnostic {@link CoreBootOptions} with the Node HTTP
+ * server required for transport attachment.
+ */
+interface BootMakaioRuntimeOptions extends CoreBootOptions {
+  /**
+   * HTTP server, already listening.
+   *
+   * The bus transport attaches its WebSocket upgrade handler to this server.
+   */
+  httpServer: Server;
+}
+/**
+ * Handle returned by `bootMakaioRuntime` on successful startup.
+ */
+interface MakaioRuntime {
+  /**
+   * Bound TCP port (read from httpServer).
+   */
+  port: number;
+  /**
+   * Bound host address (e.g. `'127.0.0.1'` or `'0.0.0.0'`).
+   */
+  host: string;
+  /**
+   * Machine identifier (UUID).
+   */
+  machineId: string;
+  /**
+   * The booted bus instance.
+   *
+   * Exposed so host composition roots can pass the live bus to seams that
+   * need a direct reference after boot (e.g. in-process workflow runner,
+   * test harnesses, host-owned contribution processors).
+   */
+  bus: IMakaioBus;
+  /**
+   * Tray manifest entries collected from all loaded packages.
+   *
+   * Each entry includes the owning `packageName` so the Electron shell can
+   * resolve the fully-qualified window registration ID
+   * (`{packageName}:{opensWindow}`) when building the tray menu.
+   *
+   * Populated during the extension coordinator's {@link ExtensionCoordinator.load}
+   * phase, before services start. Available immediately after `bootMakaioRuntime`
+   * resolves.
+   */
+  trayEntries: ReadonlyArray<TrayManifest & {
+    readonly packageName: string;
+  }>;
+  /**
+   * Window registry populated from package manifests during the extension
+   * coordinator {@link ExtensionCoordinator.load} phase.
+   *
+   * The Electron shell passes this to `WindowManager` so window
+   * creation uses the registry that was actually populated during boot,
+   * rather than an independent empty instance.
+   *
+   * Available immediately after `bootMakaioRuntime` resolves.
+   */
+  windowRegistry: WindowRegistry;
+  /**
+   * Extension coordinator that manages the lifecycle of all loaded packages.
+   *
+   * Exposed so integration tests and host composition roots can inspect the
+   * active service graph (e.g. via `getExtensionService`) after boot.
+   */
+  readonly coordinator: ExtensionCoordinator;
+  /**
+   * Shut down all services in reverse startup order.
+   */
+  shutdown(): Promise<void>;
+}
+//#endregion
+//#region runtimes/node/src/workflow-worker/types.d.ts
+/**
+ * Runtime-loaded workflow module shape consumed by the Node workflow runners.
+ */
+interface RuntimeLoadedWorkflow {
+  /** Serializable workflow definition. */
+  readonly definition: WorkflowDefinition;
+  /** Optional Zod schemas retained from workflow builder exports. */
+  readonly zodSchemas?: WorkflowZodSchemas;
+  /**
+   * Runtime station handler functions keyed by node ID.
+   * Used by the orchestrator to dispatch `station`-type nodes.
+   */
+  readonly runtimeHandlers: ReadonlyMap<string, StationHandler>;
+}
+/**
+ * Configuration options for the thin Piscina-backed workflow runner.
+ *
+ * Controls the worker-thread pool that executes workflow orchestration in isolation
+ * while delegating agent/subagent execution to the host runtime.
+ */
+interface ThinWorkflowPiscinaRunnerOptions {
+  /** Absolute path to the workflow worker entrypoint file. */
+  readonly workerEntry: string;
+  /** Contribution manifest declaring which extension packages to load in workers. */
+  readonly manifest: WorkerContributionManifest;
+  /** Maximum concurrent worker threads. @defaultValue 4 */
+  readonly maxConcurrency?: number;
+  /** Idle timeout before threads are reaped (ms). @defaultValue 30000 */
+  readonly idleTimeoutMs?: number;
+}
+//#endregion
+//#region runtimes/node/src/workflow-worker/worker-ready-message.d.ts
+/** Message type posted by workflow workers once bus control routing is ready. */
+declare const WORKFLOW_WORKER_READY_MESSAGE_TYPE: "makaio.workflow-worker.ready";
+/** Piscina worker-to-pool message emitted after cancel routing is subscribed. */
+interface WorkflowWorkerReadyMessage {
+  /** Stable message discriminator. */
+  readonly type: typeof WORKFLOW_WORKER_READY_MESSAGE_TYPE;
+  /** Workflow execution whose worker is ready. */
+  readonly executionId: string;
+  /** Dynamic workflow cancel subject observed by the worker. */
+  readonly cancelSubject: string;
+  /** Adapter identifiers loaded in the worker runtime before readiness. */
+  readonly adapters: readonly string[];
+}
+//#endregion
+//#region runtimes/node/src/workflow-worker/thin-workflow-piscina-runner.d.ts
+/** Result and readiness promises for one workflow worker dispatch. */
+interface ThinWorkflowPiscinaRunWithReadiness {
+  /** Terminal workflow result returned by the worker. */
+  readonly result: Promise<WorkflowRunResult$1>;
+  /** Resolves when the worker bus is connected and cancellation routing is subscribed. */
+  readonly ready: Promise<WorkflowWorkerReadyMessage>;
+}
+/**
+ * Thin workflow runner that dispatches workflow orchestration to a Piscina
+ * worker-thread pool.
+ *
+ * Each workflow invocation is handed off to a pooled worker thread running the
+ * `workflow-worker/worker-entry.ts` entrypoint. The worker isolates DAG control
+ * flow and worker-local toolsets, while agent/subagent execution is delegated to
+ * the host runtime. The pool manages concurrency limits and idle thread reaping
+ * automatically.
+ */
+declare class ThinWorkflowPiscinaRunner implements IWorkflowRunner$1 {
+  private readonly options;
+  private readonly manifest;
+  private pool;
+  /**
+   * @param options - Piscina runner configuration including worker entry path
+   *   and concurrency settings.
+   */
+  constructor(options: ThinWorkflowPiscinaRunnerOptions);
+  /**
+   * Execute a complete workflow in a pooled worker thread.
+   *
+   * When `manifest` is provided it overrides the runner's construction-time
+   * default, so per-request contribution sets from the WorkerNode pool are
+   * applied correctly without requiring a new runner instance.
+   * @param config - Full workflow worker configuration with source, inputs, and bus info.
+   * @param signal - AbortSignal for cooperative cancellation.
+   * @param manifest - Optional per-call manifest override.
+   * @returns Execution result with terminal status and status-specific result fields.
+   */
+  run(config: WorkflowWorkerConfig, signal: AbortSignal, manifest?: WorkerContributionManifest): Promise<WorkflowRunResult$1>;
+  /**
+   * Execute a workflow and expose the worker bus readiness signal separately.
+   *
+   * The terminal result remains the {@link IWorkflowRunner} contract. The ready
+   * promise is used by {@link PiscinaThinWorkflowProvider} so pool lifecycle
+   * `ready` is not emitted before the worker has connected its bus and subscribed
+   * to cancellation routing.
+   * @param config - Full workflow worker configuration with source, inputs, and bus info.
+   * @param signal - AbortSignal for cooperative cancellation.
+   * @param manifest - Optional per-call manifest override.
+   * @returns Terminal result and readiness promises for this worker run.
+   */
+  runWithReadiness(config: WorkflowWorkerConfig, signal: AbortSignal, manifest?: WorkerContributionManifest): ThinWorkflowPiscinaRunWithReadiness;
+  /**
+   * Destroy the thread pool and release all worker threads.
+   */
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region runtimes/node/src/workflow-worker/node-workflow-runner-factory.d.ts
+/** Parameters for composing workflow engine runner package options. */
+interface CreateNodeWorkflowRunnerPackageOptionsParams {
+  /** Runtime bus URL exposed to isolated workers. */
+  readonly busUrl: string;
+  /** Directory of the active runtime module (`src` in dev, `dist` in builds). */
+  readonly runtimeModuleDir: string;
+  /** Platform defaults forwarded to executor and worker configs. */
+  readonly platformDefaults: StepRunnerPlatformDefaults;
+  /** Optional boot-level workflow-level runner configuration. */
+  readonly workflowRunner?: WorkflowRunnerBootOptions;
+  /** Makaio data-home path forwarded to the executor config. */
+  readonly makaioHome?: string;
+  /**
+   * Host-owned bus instance forwarded to in-process runner construction.
+   *
+   * Required when `workflowRunner.mode` is `'in-process'` or omitted on an
+   * explicit runner object. Also used by WorkerNode mode when no explicit
+   * dispatch function is supplied. Ignored for Piscina mode.
+   */
+  readonly bus?: IMakaioBus;
+}
+/** Workflow engine package options produced by Node runtime composition. */
+interface NodeWorkflowRunnerPackageOptions {
+  /**
+   * Optional workflow-level runner for full-execution dispatch.
+   * When present, each new workflow execution is delegated to this runner
+   * instead of the in-process DAG scheduler.
+   */
+  readonly workflowRunner?: IWorkflowRunner;
+  /** Executor config shared by in-process and isolated modes. */
+  readonly executorConfig: {
+    /** Runtime bus URL exposed to isolated workers. */readonly busUrl: string; /** Bus authentication forwarded to workflow worker configs. */
+    readonly busAuth: StepRunnerBusAuth; /** Platform defaults forwarded to executor and worker configs. */
+    readonly platformDefaults: StepRunnerPlatformDefaults; /** Makaio data-home path forwarded to workflow workers. */
+    readonly makaioHome?: string;
+  };
+}
+/**
+ * Compose workflow engine options for workflow-level execution.
+ * @param params - Runtime module, bus, platform, and optional workflow runner.
+ * @returns Options suitable for `createWorkflowEnginePackage`.
+ */
+declare function createNodeWorkflowRunnerPackageOptions(params: CreateNodeWorkflowRunnerPackageOptionsParams): NodeWorkflowRunnerPackageOptions;
+/** Internal parameters for creating a Node workflow-level runner. */
+interface CreateNodeWorkflowRunnerParams {
+  /** Absolute path to the package root directory. */
+  readonly packageRoot: string;
+  /** Default worker entry mode (`'source'` in dev, `'dist'` in builds). */
+  readonly defaultWorkerEntryMode: WorkflowWorkerEntryMode;
+  /** Optional boot-level workflow runner configuration. */
+  readonly runner?: WorkflowRunnerBootOptions;
+  /**
+   * Host-owned bus instance forwarded to {@link InProcessWorkflowRunner}.
+   *
+   * Required when `runner` is present and its `mode` is `'in-process'` or
+   * omitted. Also required for `'worker-node'` mode when no explicit dispatch
+   * function is supplied. Ignored for Piscina mode.
+   */
+  readonly bus?: IMakaioBus;
+}
+/**
+ * Create a workflow-level runner based on the Node runtime configuration.
+ *
+ * Returns `undefined` when no runner is configured, letting the workflow engine
+ * fall back to its built-in DAG scheduler. Explicit runner modes create the
+ * matching workflow-level execution strategy.
+ * @param params - Package root, entry mode, optional runner configuration, and optional bus.
+ * @returns A workflow runner instance, or `undefined` to use the engine default.
+ */
+declare function createNodeWorkflowRunner(params: CreateNodeWorkflowRunnerParams): IWorkflowRunner | undefined;
+//#endregion
+//#region runtimes/node/src/workflow-worker/worker-node-runner.d.ts
+/**
+ * Construction options for {@link WorkerNodeRunner}.
+ */
+interface WorkerNodeRunnerOptions {
+  /**
+   * Dispatch seam injected by the host composition root.
+   *
+   * Product hosts wire this to `workerPool.dispatch` or another implementation.
+   * Framework code calls through this seam without coupling to any pool.
+   */
+  readonly dispatch: WorkerNodeDispatch;
+  /**
+   * Extension contribution manifest forwarded to dispatched workers.
+   *
+   * Omit this when the receiving dispatch layer should resolve the manifest
+   * from the selected pool or execution scope.
+   */
+  readonly manifest?: WorkerContributionManifest;
+  /**
+   * Optional resource requirements forwarded to the pool dispatch.
+   *
+   * When provided, the receiving pool uses these to select a compatible
+   * provider. Omit to accept any available pool.
+   */
+  readonly requirements?: WorkerNodeRequirements;
+}
+/**
+ * Workflow runner that delegates full workflow execution to a WorkerNode
+ * dispatch seam supplied by the host composition root.
+ *
+ * This class implements the {@link IWorkflowRunner} contract while remaining
+ * product-agnostic. Concrete dispatch behavior (e.g. pool selection, provider
+ * matching, manifest resolution) lives in the product-owned composition root
+ * or `workerPool.dispatch` handler, not here.
+ */
+declare class WorkerNodeRunner implements IWorkflowRunner {
+  private readonly options;
+  /**
+   * @param options - Dispatch seam, optional manifest, and optional requirements.
+   */
+  constructor(options: WorkerNodeRunnerOptions);
+  /**
+   * Execute a complete workflow by delegating to the injected dispatch seam.
+   *
+   * When `manifest` is supplied it takes precedence over the manifest baked into
+   * the runner at construction time, enabling per-call contribution sets.
+   * @param config - Full workflow worker configuration including source, inputs, and bus info.
+   * @param signal - AbortSignal for cooperative cancellation forwarded to the dispatch function.
+   * @param manifest - Optional per-call contribution manifest. Overrides the runner's default.
+   * @param options - Optional per-run controls forwarded to dispatch-capable providers.
+   * @returns The execution result with terminal status and status-specific result fields.
+   */
+  run(config: WorkflowWorkerConfig, signal: AbortSignal, manifest?: WorkerContributionManifest, options?: WorkflowRunnerRunOptions): Promise<WorkflowRunResult>;
+}
+//#endregion
+//#region runtimes/node/src/workflow-worker/piscina-thin-workflow-provider.d.ts
+/**
+ * Construction options for {@link PiscinaThinWorkflowProvider}.
+ */
+interface PiscinaThinWorkflowProviderOptions {
+  /** Stable unique identifier for this provider instance. */
+  readonly id: string;
+  /** Human-readable label for display in UI and logs. */
+  readonly displayName: string;
+  /**
+   * Underlying workflow runner used to execute incoming provision requests.
+   *
+   * Typically a {@link ThinWorkflowPiscinaRunner} instance, but any
+   * {@link IWorkflowRunner} implementation is accepted so tests can supply
+   * lightweight fakes without spawning real worker threads.
+   */
+  readonly runner: IWorkflowRunner;
+  /**
+   * Capabilities advertised when this provider is registered.
+   *
+   * Overrides are merged onto the built-in local, delegating workflow
+   * capability set. The Piscina runner shares the host process filesystem and
+   * delegates agent/subagent execution to the host runtime.
+   */
+  readonly baseCapabilities?: Partial<WorkerNodeCapabilities>;
+}
+/**
+ * Built-in thin workflow provider backed by the existing workflow-level Piscina runner.
+ *
+ * This provider wraps an {@link IWorkflowRunner} so it can be registered with
+ * the framework capability registry and participate in pool-driven dispatch.
+ * Each {@link provision} call starts the underlying runner and returns a
+ * {@link WorkerNodeHandle} that callers use to wait for the result or request
+ * cancellation. Pool-level dispatch owns WorkerNode lifecycle events because it
+ * also owns cancellation ordering and terminal state emission.
+ */
+declare class PiscinaThinWorkflowProvider implements IWorkerNodeProvider {
+  private readonly options;
+  /** Execution environment tag used for pool provider matching. */
+  readonly environment: "piscina";
+  /** Capabilities advertised to the pool dispatch selector. */
+  readonly baseCapabilities: NormalizedWorkerNodeCapabilities;
+  /**
+   * @param options - Provider identity, runner, and optional capability overrides.
+   */
+  constructor(options: PiscinaThinWorkflowProviderOptions);
+  /** @returns Unique identifier for this provider instance. */
+  get id(): string;
+  /** @returns Human-readable display name for this provider. */
+  get displayName(): string;
+  /**
+   * Provision a new isolated execution node for the given workflow request.
+   *
+   * Starts the underlying runner and returns a handle that the caller holds
+   * until the execution reaches a terminal state. Cancellation flows through
+   * the handle's `cancel` / `terminate` methods, which abort the internal
+   * `AbortController` wired to the runner's signal.
+   * @param request - Full provision request containing worker config and manifest.
+   * @returns A handle for the provisioned node with wait, cancel, and terminate operations.
+   */
+  provision(request: WorkerNodeProvisionRequest): Promise<WorkerNodeHandle>;
+}
+//#endregion
+//#region runtimes/node/src/workflow-worker/in-process-workflow-runner.d.ts
+/**
+ * Constructor options for {@link InProcessWorkflowRunner}.
+ */
+interface InProcessWorkflowRunnerOptions {
+  /**
+   * Bus instance shared with the host runtime.
+   *
+   * The runner does not boot its own bus or runtime services — it reuses the
+   * caller-owned bus so workflow orchestration participates in the same event
+   * fabric as all other framework services.
+   */
+  readonly bus: IMakaioBus;
+}
+/**
+ * In-process implementation of {@link IWorkflowRunner}.
+ *
+ * Executes a full workflow inside the calling process using the shared host
+ * bus. Unlike the Piscina and WorkerNode runners, this runner does not spawn
+ * isolated processes or threads — the workflow orchestrator runs inline on the
+ * caller's bus.
+ *
+ * Use this runner when the host process already owns a fully-booted bus and
+ * the workflow's step types do not require process isolation (e.g. pure shell,
+ * agent, and gate steps sourced from a serialized definition).
+ *
+ * The bus lifecycle is owned by the caller. This runner holds no disposable
+ * resources of its own, so `dispose()` is intentionally omitted.
+ */
+declare class InProcessWorkflowRunner implements IWorkflowRunner {
+  #private;
+  /**
+   * @param options - Options including the caller-owned bus instance.
+   */
+  constructor(options: InProcessWorkflowRunnerOptions);
+  /**
+   * Execute a complete workflow in-process using the shared host bus.
+   *
+   * Steps:
+   * 1. Load the workflow from the config source descriptor.
+   * 2. Pass the loaded workflow, config, bus, and signal to the orchestrator.
+   *
+   * The `manifest` parameter is accepted for interface conformance but is
+   * unused — in-process execution does not load worker-local contributions.
+   * @param config - Workflow worker configuration to validate before execution.
+   * @param signal - AbortSignal for cooperative cancellation.
+   * @param _manifest - Ignored; in-process runners share the host contribution set.
+   * @returns The terminal workflow run result.
+   */
+  run(config: WorkflowWorkerConfig, signal: AbortSignal, _manifest?: WorkerContributionManifest): Promise<WorkflowRunResult>;
+}
+//#endregion
+//#region runtimes/node/src/workflow-worker/workflow-loader.d.ts
+/**
+ * Resolve a {@link RuntimeLoadedWorkflow} from the parsed worker config.
+ *
+ * Routing rules:
+ * - `source.kind === 'definition'` with a populated `config.definition`:
+ *   builds the {@link RuntimeLoadedWorkflow} in-place from the serialized definition.
+ *   Pipeline-primitive definitions are fully serializable, so `runtimeHandlers`
+ *   is always an empty Map for definition-sourced dispatch.
+ * - All other source kinds delegate to the file-loader which handles `'path'`
+ *   and `'source'` variants.
+ * @param config - Parsed and validated worker configuration.
+ * @returns The loaded workflow ready for the orchestrator.
+ * @throws When `source.kind === 'definition'` but `config.definition` is absent.
+ */
+declare function loadWorkflowFromConfig(config: WorkflowWorkerConfig): Promise<RuntimeLoadedWorkflow>;
+//#endregion
+//#region runtimes/node/src/workflow-worker/workflow-file-loader.d.ts
+/**
+ * Load one or more workflow modules from the given source descriptor and
+ * return a normalized array.
+ *
+ * Supports two source kinds:
+ * - `'path'`: dynamically imports the file at `source.path` via a `file://` URL.
+ * - `'source'`: writes inline ESM code to a temp file, imports it, then
+ *   removes the temp directory.
+ *
+ * Each module's default export may be either a single workflow object or a
+ * bundle `{ workflows: [...] }`. Both are normalized to a flat
+ * `RuntimeLoadedWorkflow[]`.
+ * @param source - Workflow source descriptor (must not be `'definition'` kind).
+ * @returns Array of loaded workflows with `definition` and `runtimeHandlers`.
+ * @throws When the module shape is invalid or any workflow entry fails validation.
+ */
+declare function loadWorkflowModules(source: Exclude<WorkflowWorkerSource, {
+  kind: 'definition';
+}>): Promise<RuntimeLoadedWorkflow[]>;
+/**
+ * Load a single workflow module from the given source descriptor.
+ *
+ * A convenience wrapper around {@link loadWorkflowModules} for the common
+ * single-workflow case. Throws if the source resolves to a bundle with more
+ * than one workflow.
+ *
+ * Supports two source kinds:
+ * - `'path'`: dynamically imports the file at `source.path` via a `file://` URL.
+ * - `'source'`: writes inline ESM code to a temp file, imports it, then
+ *   removes the temp directory.
+ *
+ * `'definition'`-sourced workers bypass the file loader entirely — they are
+ * handled by the workflow executor which has access to the registered
+ * definition registry. Calling this function with `kind === 'definition'`
+ * always throws.
+ * @param source - Workflow source descriptor from `WorkflowWorkerConfig.source`.
+ * @returns Loaded workflow with `definition` and `runtimeHandlers`.
+ * @throws For `'definition'` kind, when the module shape is invalid, or when
+ *   the module exports a bundle containing more than one workflow.
+ */
+declare function loadWorkflowModule(source: WorkflowWorkerSource): Promise<RuntimeLoadedWorkflow>;
+//#endregion
+export { normalizeNodeHostCapabilities as A, HttpContributionPhase as B, TransportReadyInfo as C, WorkflowWorkerEntryResolverOptions as D, WorkflowWorkerEntryMode as E, NodeFrameworkModuleResolver as F, HonoRouteGraph as H, NoopFrameworkModuleResolver as I, resolveFrameworkSpecifier as L, ShutdownStep as M, BridgeBrowserOptions as N, resolveWorkflowWorkerEntry as O, FrameworkModuleResolver as P, HttpRouteGraphBuilder as R, ServerTransportProvider as S, WorkflowRunnerBootOptions as T, HonoRouteGraphOptions as U, HttpRouteContribution as V, createHonoRouteGraph as W, WorkflowRunResult$1 as _, InProcessWorkflowRunnerOptions as a, CoreBootOptions as b, WorkerNodeRunner as c, NodeWorkflowRunnerPackageOptions as d, createNodeWorkflowRunner as f, ThinWorkflowPiscinaRunnerOptions as g, IWorkflowRunner$1 as h, InProcessWorkflowRunner as i, selectFrameworkCorePackages as j, HostCapabilityDeclaration as k, WorkerNodeRunnerOptions as l, ThinWorkflowPiscinaRunner as m, loadWorkflowModules as n, PiscinaThinWorkflowProvider as o, createNodeWorkflowRunnerPackageOptions as p, loadWorkflowFromConfig as r, PiscinaThinWorkflowProviderOptions as s, loadWorkflowModule as t, CreateNodeWorkflowRunnerPackageOptionsParams as u, BootCoordinatorSetupContext as v, UpstreamTelemetryBootOptions as w, MakaioRuntime as x, BootMakaioRuntimeOptions as y, createHttpRouteGraphBuilder as z };