@makaio/framework 1.0.0-dev-1784889676396 → 1.0.0-dev-1785347612784

package/dist/package-DWMxGfzK.d.mts

@@ -0,0 +1,827 @@
+import { l as ProviderOperationOwnershipRecord, o as ProviderOperationClaimDecision, s as ProviderOperationMutationDecision } from "./provider-operation-Cxoe2SUr.mjs";
+import { A as RecoverableAttemptRecord, C as ProvisioningClaimDecision, D as RecordProviderOperationUncertaintyInput, E as RecordInfrastructureFailureInput, M as TakeOverProviderOperationInput, O as RecordProvisionerIncarnationLostInput, S as ProvisioningAbsenceDecision, T as RecordAllocationTerminatedInput, a as BeginProvisioningInput, b as PendingAttemptAbandonmentDecision, f as ExecutionAttemptOutcomeDecision, h as ExecutionAttemptRepository, i as AllocationTerminationDecision, j as RenewProviderOperationClaimInput, k as RecordProvisioningAbsentInput, n as AllocationRefEvolution, o as DiscoveredAllocationDecision, p as ExecutionAttemptRecord, r as AllocationRefEvolutionDecision, t as AllocationRecordingDecision, v as HandoffProviderOperationInput, w as RecordAllocationInput, x as ProvisionerIncarnationLossDecision, y as InfrastructureFailureDecision } from "./execution-attempt-repository-DWXKY41_.mjs";
+import { IMakaioBus } from "@makaio/framework/bus";
+import * as _$_makaio_contracts0 from "@makaio/framework/contracts";
+import { IWorkflowRunner, IWorkflowTriggerTypeRegistry, LoopGateHandler, MakaioNodeExtension, StationHandler, StepRunnerBusAuth, StepRunnerPlatformDefaults, WorkerMaterializationSpec, WorkflowDefinition, WorkflowExecution, WorkflowRunContext, WorkflowRunResult } from "@makaio/framework/contracts";
+import { BaseService } from "@makaio/framework/service-base";
+import { MakaioDatabase } from "@makaio/framework/storage/drizzle";
+
+//#region subsystems/workflow-engine/src/storage/handler.d.ts
+/**
+ * Registers all Drizzle-based workflow storage handlers with the bus.
+ *
+ * Handles:
+ * - Definition CRUD: get, set, delete, list
+ * - Execution CRUD: getExecution, setExecution, updateExecution, listExecutions, listExecutionsByArtifactRefs
+ * - Frame CRUD: setFrame, getFrame, listFrames
+ * - Gate instance CRUD: setGateInstance, getGateInstance, listGateInstances
+ * - Span CRUD: setSpan, listSpans
+ * - Execution link CRUD: setExecutionLink, listExecutionLinks
+ * - Run context CRUD: setRunContext, getRunContext
+ * - WorkLog projection: execution/frame reads, stats, and changed events
+ * @param bus - MakaioBus instance for message handling
+ * @param db - Drizzle database instance
+ * @returns Cleanup function to unregister all handlers
+ */
+declare function registerDrizzleWorkflowStorage(bus: IMakaioBus, db: MakaioDatabase): () => void;
+//#endregion
+//#region subsystems/workflow-engine/src/types.d.ts
+/**
+ * Resolve a portable workspace identifier to an allowed local root directory.
+ *
+ * Returning `undefined` delegates resolution to the next registered resolver.
+ * @param workspaceId - Portable workspace identifier from a materialization spec.
+ * @returns Absolute allowed root, or `undefined` when this resolver does not own the identifier.
+ */
+type WorkflowWorkspaceRootResolver = (workspaceId: string) => Promise<string | undefined>;
+/**
+ * Configuration for the workflow executor.
+ */
+interface ExecutorConfig {
+  /** Timeout for individual step execution in ms. */
+  stepTimeoutMs: number;
+  /** Cooldown between steps in ms. */
+  stepCooldownMs: number;
+  /** Bus server WebSocket URL for runner worker connections. */
+  busUrl?: string;
+  /** Bus authentication strategy for runner worker connections. */
+  busAuth: StepRunnerBusAuth;
+  /** Platform-level defaults (cwd, env) for runner process creation. */
+  platformDefaults: StepRunnerPlatformDefaults;
+  /** Grace period in ms before forceKill is issued after cooperative abort. */
+  cancelTimeoutMs: number;
+  /**
+   * Absolute path to the Makaio data-home directory.
+   *
+   * Used by the in-process executor to populate the ephemeral platform
+   * context exposed to station handlers. When omitted the executor derives
+   * a default from the `MAKAIO_HOME` environment variable or `~/.makaio`.
+   */
+  makaioHome?: string;
+}
+/**
+ * Input used by a host to resolve a durable workspace reference for a
+ * path-backed workflow start.
+ */
+interface WorkflowMaterializationSpecResolution {
+  /** Durable execution identity being created. */
+  readonly executionId: string;
+  /** Definition identity selected for the execution. */
+  readonly workflowId: string;
+  /** Process-local path supplied by the start request or definition. */
+  readonly sourcePath: string;
+  /** Coordinator workspace root selected for the execution. */
+  readonly workspaceRoot: string;
+}
+/**
+ * Host seam for resolving an immutable workspace reference before a
+ * path-backed run context is persisted.
+ */
+interface WorkflowMaterializationSpecResolver {
+  /** Resolve the portable materialization spec for one execution start. */
+  resolve(input: WorkflowMaterializationSpecResolution): Promise<WorkerMaterializationSpec | undefined>;
+}
+//#endregion
+//#region subsystems/workflow-engine/src/execution-attempt-authority.d.ts
+/**
+ * Execution attempt Authority service.
+ *
+ * Owns:
+ * - attempt ID generation (`crypto.randomUUID()`);
+ * - current-process waiters so runners can `await` a committed outcome;
+ * - idempotent workflow-state convergence for both `accepted` and `duplicate`.
+ *
+ * Delegates:
+ * - durable attempt creation, provider-operation ownership, allocation
+ *   recording, and outcome commit decisions to the injected
+ *   {@link ExecutionAttemptRepository}.
+ *
+ * The Authority never invents controller identity, lease policy, or fencing
+ * tokens, and never chooses a provider operation's obligation. It passes the
+ * host-owned claim context through and reports the repository's decision.
+ *
+ * **Waiter settlement invariant:** waiters settle only on converged
+ * outcomes (via {@link settleOutcome}) or on definitive rejection
+ * (`conflict`, `fenced`, infrastructure failure). A committed-but-unconverged
+ * outcome leaves the waiter pending so retries can converge and settle it.
+ * Recovery of committed-but-unconverged outcomes across process restarts
+ * is the host recovery coordinator's concern via the exported recovery
+ * operations.
+ *
+ * This service is stateless across process restarts. In-process waiters
+ * are lost on crash; the host recovery coordinator owns recovery decisions.
+ */
+declare class ExecutionAttemptAuthority {
+  private readonly repository;
+  /**
+   * In-process waiters keyed by `executionAttemptId`.
+   *
+   * A waiter is created in {@link createAttempt} and settled via
+   * {@link settleOutcome} after convergence. Callers use
+   * {@link waitForOutcome} to obtain the promise.
+   */
+  private readonly waiters;
+  /**
+   * @param repository - Injected durable attempt persistence port.
+   */
+  constructor(repository: ExecutionAttemptRepository);
+  /**
+   * Create a new execution attempt with an Authority-generated ID.
+   *
+   * Persists the attempt through the repository and installs an in-process
+   * waiter for the committed outcome. Must be called before dispatch.
+   * @param executionId - Workflow execution identifier.
+   * @returns The persisted attempt record.
+   */
+  createAttempt(executionId: string): Promise<ExecutionAttemptRecord>;
+  /**
+   * Claim durable ownership of provider provisioning for an active attempt.
+   *
+   * Delegates directly to the repository immediately before a provider call.
+   * A `started` decision is the sole authorization for that call, and it
+   * carries the claim every subsequent provider-side record must present.
+   * @param input - Attempt identity, immutable provider binding, and initial claim context.
+   * @returns The durable provisioning ownership decision.
+   */
+  beginProvisioning(input: BeginProvisioningInput): Promise<ProvisioningClaimDecision>;
+  /**
+   * Read the current provider operation for an attempt.
+   * @param executionAttemptId - Attempt whose operation to read.
+   * @returns The ownership record, or `null` when provisioning never began.
+   */
+  getProviderOperation(executionAttemptId: string): Promise<ProviderOperationOwnershipRecord | null>;
+  /**
+   * Extend the lease of a currently held provider operation.
+   * @param input - Current claim and the new lease deadline.
+   * @returns The durable claim decision.
+   */
+  renewProviderOperationClaim(input: RenewProviderOperationClaimInput): Promise<ProviderOperationClaimDecision>;
+  /**
+   * Take ownership of an unowned or lease-expired provider operation.
+   * @param input - Attempt identity, requesting owner, observation time, and lease deadline.
+   * @returns The durable claim decision.
+   */
+  takeOverProviderOperation(input: TakeOverProviderOperationInput): Promise<ProviderOperationClaimDecision>;
+  /**
+   * Release a held provider operation without resolving it.
+   *
+   * The attempt keeps its durable state and stays remediable, so the local
+   * waiter is left untouched: handoff transfers control, it does not answer
+   * the workflow.
+   * @param input - Claim being released and optional bounded release evidence.
+   * @returns The durable mutation decision.
+   */
+  handoffProviderOperation(input: HandoffProviderOperationInput): Promise<ProviderOperationMutationDecision>;
+  /**
+   * Record that a provider observation stayed inconclusive.
+   *
+   * Non-terminal by construction: the waiter stays pending because the
+   * attempt still has no canonical answer.
+   * @param input - Claim and bounded evidence describing the retained uncertainty.
+   * @returns The durable mutation decision.
+   */
+  recordProviderOperationUncertainty(input: RecordProviderOperationUncertaintyInput): Promise<ProviderOperationMutationDecision>;
+  /**
+   * Record the provider allocation reference for a claimed operation.
+   * @param input - Claim and the validated allocation reference.
+   * @returns The durable allocation ownership decision.
+   */
+  recordAllocation(input: RecordAllocationInput): Promise<AllocationRecordingDecision>;
+  /**
+   * Record positively proven absence of any allocation for the attempt.
+   *
+   * A recorded absence settles the attempt as `abandoned`, so its waiter is
+   * rejected and removed. The bounded evidence is durable in the operation
+   * record; the local error only mirrors it for the in-process caller.
+   * @param input - Claim, owning execution, and bounded absence evidence.
+   * @returns The durable absence decision.
+   */
+  recordProvisioningAbsent(input: RecordProvisioningAbsentInput): Promise<ProvisioningAbsenceDecision>;
+  /**
+   * Close pre-allocation debt on proof that a provisioner incarnation is gone.
+   *
+   * A recorded loss settles the attempt as `abandoned`, so its waiter is
+   * rejected and removed. The bounded proof evidence is durable in the
+   * operation record; the local error only mirrors it for the in-process
+   * caller.
+   * @param input - Claim, owning execution, and the provisioner loss proof.
+   * @returns The durable provisioner-loss decision.
+   */
+  recordProvisionerIncarnationLost(input: RecordProvisionerIncarnationLostInput): Promise<ProvisionerIncarnationLossDecision>;
+  /**
+   * Record that a known allocation was confirmed terminated.
+   *
+   * Advances the operation to terminal convergence without settling the
+   * attempt, so the waiter stays pending until a canonical answer exists.
+   * @param input - Claim and bounded evidence supporting the termination.
+   * @returns The durable termination decision.
+   */
+  recordAllocationTerminated(input: RecordAllocationTerminatedInput): Promise<AllocationTerminationDecision>;
+  /**
+   * Retrieve the active attempt for a given execution.
+   *
+   * Delegates directly to the repository.
+   * @param executionId - Workflow execution identifier.
+   * @param executionAttemptId - Attempt identifier to look up.
+   * @returns The attempt record if active, or `null`.
+   */
+  getActiveAttempt(executionId: string, executionAttemptId: string): Promise<ExecutionAttemptRecord | null>;
+  /**
+   * Commit a terminal outcome for an attempt.
+   *
+   * Delegates the durable decision to the repository. For `conflict` and
+   * `fenced` decisions, the in-process waiter is rejected immediately because
+   * no convergence step follows. For `accepted` and `duplicate` decisions, the
+   * waiter is NOT settled here — the caller must invoke {@link settleOutcome}
+   * after workflow-state convergence succeeds.
+   * @param executionAttemptId - The attempt submitting the outcome.
+   * @param executionId - Workflow execution identifier.
+   * @param result - Terminal workflow result to commit.
+   * @returns The durable decision with the canonical outcome when applicable.
+   */
+  commitOutcome(executionAttemptId: string, executionId: string, result: WorkflowRunResult): Promise<ExecutionAttemptOutcomeDecision>;
+  /**
+   * Obtain the in-process promise for a committed outcome.
+   *
+   * Returns `undefined` when no waiter exists for the given attempt
+   * (e.g. after a process restart or for attempts created by other hosts).
+   * @param executionAttemptId - The attempt to wait for.
+   * @returns Promise that resolves with the canonical workflow result, or `undefined`.
+   */
+  waitForOutcome(executionAttemptId: string): Promise<WorkflowRunResult> | undefined;
+  /**
+   * Settle the in-process waiter after workflow-state convergence succeeds.
+   *
+   * Called by the outcome-submission handler only after the durable workflow
+   * transition has completed. This ensures runners observe the committed
+   * outcome only when canonical workflow state is consistent.
+   * @param executionAttemptId - The attempt whose waiter to settle.
+   * @param decision - The durable outcome decision (must be accepted or duplicate).
+   */
+  settleOutcome(executionAttemptId: string, decision: ExecutionAttemptOutcomeDecision): void;
+  /**
+   * Remove an in-process waiter without settling it.
+   *
+   * Used when the caller no longer needs to wait (e.g. cancellation before
+   * outcome submission).
+   * @param executionAttemptId - The attempt whose waiter should be removed.
+   */
+  discardWaiter(executionAttemptId: string): void;
+  /**
+   * Reject and remove an in-process waiter without making a durable attempt claim.
+   *
+   * Use only when local dispatch ownership cannot safely await canonical
+   * terminalization, such as an unconfirmed provider cleanup. The durable
+   * attempt remains unchanged for recovery or operator remediation.
+   * @param executionAttemptId - Attempt whose local waiter must be rejected.
+   * @param error - Local failure delivered to the current-process waiter.
+   */
+  rejectAndDiscardWaiter(executionAttemptId: string, error: Error): void;
+  /**
+   * Reject and remove a waiter with an error built only if one is waiting.
+   *
+   * Every durable transition that rejects a waiter is also the transition a
+   * remediating process runs after a restart, where by definition no waiter
+   * from the original dispatch survives. Building the `Error` — and capturing
+   * a stack for it — before looking would make that the common case, and it is
+   * the case where the error is never delivered to anyone.
+   * @param executionAttemptId - Attempt whose local waiter must be rejected.
+   * @param describeFailure - Builds the failure, called only when a waiter exists.
+   */
+  private rejectWaiterWith;
+  /**
+   * Whether the injected repository supports recovery operations.
+   *
+   * Recovery is one indivisible capability on the port, so this is one
+   * presence check rather than four: a repository either carries the
+   * {@link ExecutionAttemptRecoveryOperations} object or it does not.
+   * @returns `true` when the repository exposes its recovery operations.
+   */
+  get supportsRecovery(): boolean;
+  /**
+   * Look up an attempt by its identifier, regardless of active status.
+   *
+   * Delegates to the repository's `getAttemptWithAllocation` operation.
+   * Throws when the repository does not support recovery.
+   * @param executionAttemptId - The attempt to look up.
+   * @returns The attempt record, or `null` if no such attempt exists.
+   */
+  getAttemptWithAllocation(executionAttemptId: string): Promise<ExecutionAttemptRecord | null>;
+  /**
+   * Record an allocation that provider discovery found for the attempt.
+   *
+   * Delegates to the repository's `recordDiscoveredAllocation` operation.
+   * Throws when the repository does not support recovery.
+   * @param input - Claim and the discovered allocation reference.
+   * @returns The durable discovered-allocation decision.
+   */
+  recordDiscoveredAllocation(input: RecordAllocationInput): Promise<DiscoveredAllocationDecision>;
+  /**
+   * Compare-and-set update of the allocation reference for a claimed attempt.
+   *
+   * Validates that `currentRef` and `nextRef` share the same `providerId`
+   * before delegating to the repository. Provider identity must not change
+   * during correlation — only the opaque `providerData` evolves.
+   * @param input - CAS evolution input with current and next references.
+   * @returns The evolution decision.
+   */
+  evolveAllocationRef(input: AllocationRefEvolution): Promise<AllocationRefEvolutionDecision>;
+  /**
+   * List all recoverable (allocated, non-settled) attempts for an execution.
+   *
+   * Delegates to the repository's `getRecoverableAttempts` operation.
+   * Throws when the repository does not support recovery.
+   * @param executionId - Workflow execution identifier.
+   * @returns Allocated, non-settled attempts eligible for recovery, oldest first.
+   */
+  getRecoverableAttempts(executionId: string): Promise<readonly RecoverableAttemptRecord[]>;
+  /**
+   * Record a confirmed infrastructure failure for an allocated attempt.
+   *
+   * Delegates the durable decision to the repository. When the failure is
+   * recorded, rejects the in-process waiter (if any) so runners observe
+   * the infrastructure failure immediately.
+   * @param input - Claim and the owning execution.
+   * @returns The infrastructure failure decision.
+   */
+  recordInfrastructureFailure(input: RecordInfrastructureFailureInput): Promise<InfrastructureFailureDecision>;
+  /**
+   * Durably abandon a dispatch attempt that did not receive an allocation.
+   *
+   * The repository refuses to use this transition for allocated attempts so a
+   * dispatcher cannot silently strand live infrastructure.
+   * @param executionAttemptId - Attempt whose pre-allocation dispatch ended.
+   * @param executionId - Workflow execution identifier.
+   * @returns The durable abandonment decision.
+   */
+  abandonPendingAttempt(executionAttemptId: string, executionId: string): Promise<PendingAttemptAbandonmentDecision>;
+  /**
+   * Obtain the repository's recovery operations, or refuse the call.
+   * @param operation - The recovery operation being attempted.
+   * @returns The repository's recovery operations.
+   * @throws When the repository does not implement recovery operations.
+   */
+  private requireRecovery;
+  /**
+   * Install an in-process waiter for the given attempt.
+   * @param executionAttemptId - Attempt to install a waiter for.
+   */
+  private installWaiter;
+  /**
+   * Settle the in-process waiter based on a repository decision.
+   *
+   * For accepted/duplicate, resolves with the canonical outcome.
+   * For conflict/fenced, rejects with a descriptive error.
+   * @param executionAttemptId - Attempt whose waiter to settle.
+   * @param decision - The durable outcome decision from the repository.
+   */
+  private settleWaiterInternal;
+}
+//#endregion
+//#region subsystems/workflow-engine/src/workflow-executor.d.ts
+/**
+ * Core workflow executor service.
+ *
+ * Orchestrates workflow execution lifecycle:
+ * - Creates coordinator session for each execution
+ * - Executes steps via the mutable DAG scheduler
+ * - Spawns subagents for each step
+ * - Tracks progress and emits lifecycle events
+ * - Manages cancellation and cleanup
+ */
+declare class WorkflowExecutor extends BaseService {
+  /** Drizzle storage handler registration for the composition root. */
+  static readonly storage: {
+    readonly drizzle: typeof registerDrizzleWorkflowStorage;
+  };
+  private readonly config;
+  private readonly activeExecutions;
+  private readonly executionTasks;
+  private readonly shellAbortControllers;
+  private readonly activeRunnerSteps;
+  private readonly gateTimeoutScheduler;
+  private readonly resumeDispatches;
+  /**
+   * Per-execution abort controllers used to cancel workflow-level runners.
+   * Keyed by execution ID; only populated when a {@link IWorkflowRunner} is used.
+   */
+  private readonly workflowAbortControllers;
+  private readonly successFinalizers;
+  private readonly durableLifecycleTransitions;
+  private readonly lifecyclePublications;
+  private readonly publishingLifecycleExecutions;
+  private readonly workflowRunner?;
+  private readonly executionAttemptAuthority?;
+  private readonly materializationSpecResolvers;
+  private triggerTypeRegistry?;
+  /**
+   * Create a new workflow executor.
+   * @param bus - The message bus for communication
+   * @param config - Optional partial configuration (merged with defaults)
+   * @param workflowRunner - Optional workflow-level runner for isolated execution
+   * @param executionAttemptAuthority - Optional Authority for WorkerNode dispatch runners
+   */
+  constructor(bus: IMakaioBus, config?: Partial<ExecutorConfig>, workflowRunner?: IWorkflowRunner, executionAttemptAuthority?: ExecutionAttemptAuthority);
+  /**
+   * Set the trigger type registry for listTriggerTypes support.
+   * @param registry - Trigger type registry instance
+   */
+  setTriggerTypeRegistry(registry: IWorkflowTriggerTypeRegistry): void;
+  /**
+   * Retrieve the registry set via {@link setTriggerTypeRegistry}.
+   *
+   * The composition root calls this after boot to wire
+   * `setWorkflowTriggerTypeRegistry` from `@makaio/kernel`.
+   * @returns The trigger type registry, or `undefined` if not yet set.
+   */
+  getTriggerTypeRegistry(): IWorkflowTriggerTypeRegistry | undefined;
+  /**
+   * Register a host resolver used to freeze workspace materialization before a
+   * path-backed execution is persisted.
+   * @param resolver - Host-owned resolver.
+   * @returns Idempotent cleanup that unregisters this resolver.
+   */
+  registerWorkflowMaterializationSpecResolver(resolver: WorkflowMaterializationSpecResolver): () => void;
+  /**
+   * Register one named finalizer eligible for compiled workflow success transitions.
+   *
+   * A workflow selects this registration through its immutable
+   * `successFinalizerId` definition field. Disposing the returned registration
+   * leaves already-claimed work recoverable only when the same ID is registered
+   * again on a later executor instance.
+   * @param finalizerId - Stable finalizer identity used by the durable claim.
+   * @returns Idempotent cleanup after any recoverable claims have been drained.
+   * @throws When another active registration already owns `finalizerId`.
+   */
+  registerSuccessFinalizer(finalizerId: string): Promise<() => void>;
+  /**
+   * Accept a terminal result from an authority-dispatched runner that was not
+   * launched through this executor's in-memory task registry.
+   *
+   * Durable execution and run-context rows remain the source of truth. The
+   * executor temporarily adopts a missing active entry and delegates to the
+   * same runner-result finalization path used by executor-owned tasks.
+   * @param executionId - Durable authority-owned execution identity.
+   * @param result - Correlated terminal runner result.
+   * @returns The durable status after acceptance, including pending success finalization.
+   */
+  acceptAuthorityRunnerResult(executionId: string, result: WorkflowRunResult): Promise<{
+    accepted: boolean;
+    status: WorkflowExecution['status'];
+  }>;
+  private resolveAuthorityRunnerReplay;
+  private loadAuthorityRunnerContext;
+  private registerAuthorityResultFinalizer;
+  /**
+   * Register all bus handlers via BaseService lifecycle.
+   * Called once by `init()` — idempotency is handled by BaseService.
+   */
+  protected onInit(): Promise<void>;
+  /**
+   * Release in-flight executions and abort shell processes.
+   * Called by `destroy()` before handler unsubscription.
+   */
+  protected onDestroy(): Promise<void>;
+  /**
+   * Build a {@link FinalizerDeps} bundle from current instance state.
+   *
+   * Extracted to avoid duplicating the same field enumeration across the cancel
+   * handler, the shutdown path, and the runner rejection catch path.
+   * @returns Finalizer dependency bundle.
+   */
+  private buildFinalizerDeps;
+  /**
+   * Build a {@link RunnerTaskDeps} bundle for delegating to
+   * {@link buildExecutionTask} or {@link buildFileExecutionTask}.
+   * @param workflowRunner - The runner instance to use (always defined at these call sites).
+   * @returns Runner task dependency bundle.
+   */
+  private buildRunnerTaskDeps;
+  /**
+   * Resolve the workspace root inherited from a parent session.
+   *
+   * Coordinator sessions are created with this target working directory so
+   * in-process shell steps and workflow-level workers share the same workspace.
+   *
+   * Throws when a `parentSessionId` is supplied but the session does not exist.
+   * The session create handler enforces the same invariant, but throwing here
+   * provides a cleaner error before any coordinator session is created.
+   * @param parentSessionId - Optional parent session identifier.
+   * @returns Parent session working directory, or the executor default cwd.
+   * @throws When `parentSessionId` is provided but the session is not found.
+   */
+  private resolveExecutionWorkspaceRoot;
+  /**
+   * Derive ephemeral platform fields from the current process environment.
+   *
+   * Delegates to the shared {@link resolveEphemeralPlatformFields} helper
+   * with config-specific overrides for workspace root and Makaio home.
+   * @returns Ephemeral platform fields for the current machine.
+   */
+  private resolveEphemeralPlatformFields;
+  /**
+   * Build the {@link StartExecutionDeps} bundle used by {@link startExecution}
+   * and {@link startFileExecution}.
+   * @returns Start execution dependency bundle.
+   */
+  private buildStartDeps;
+  /** Register execution control handlers (start, cancel). */
+  private registerExecutionHandlers;
+  /** Register timeout wakeup handlers for parked gates. */
+  private registerGateTimeoutHandlers;
+  /**
+   * Rebuild timeout wakeups for exit-based gates left waiting across executor restarts.
+   *
+   * Gate rows persist the effective timeout policy captured when the reviewer
+   * prompt opened, so rehydration does not depend on the current workflow
+   * definition or a definition snapshot being available. Expired deadlines are
+   * scheduled with zero delay and redispatched by the same persisted-gate
+   * timeout path used for live suspensions.
+   */
+  private rehydratePausedGateTimeouts;
+  /**
+   * Main execution loop — drives the primitive runtime over the workflow's
+   * root sequence node.
+   *
+   * Creates a per-execution `RuntimeContext` and `AbortController`, then
+   * delegates to {@link executeSequence} to walk the node tree. The abort
+   * controller is registered in `workflowAbortControllers` so the cancel
+   * handler can interrupt a running execution.
+   * @param executionId - The execution ID.
+   */
+  private runExecution;
+  /**
+   * Accept a gate response for an execution that is paused in storage.
+   *
+   * Checks that the execution is paused, the response targets a waiting gate
+   * frame directly or by a unique gate node, and the submitted resume data
+   * matches the persisted gate schema. On a valid response, updates the gate
+   * instance to its resolved state and triggers a resume dispatch via
+   * {@link resumePausedExecution}.
+   *
+   * Returns `false` without modifying state when the execution is not paused
+   * or the gate response is ambiguous or invalid, allowing the bus to continue
+   * to the next handler.
+   * @param payload - Gate response payload from the bus request context.
+   * @returns `true` when the gate was accepted and resume dispatched; `false` otherwise.
+   */
+  private respondToPausedGate;
+  /**
+   * Transition a paused execution back to running and re-dispatch it through
+   * the configured runner infrastructure.
+   * @param executionId - Execution to resume.
+   */
+  private resumePausedExecution;
+  /**
+   * Dispatch a paused execution once durable resume state is available.
+   * @param executionId - Execution to resume.
+   * @returns True when a runner task was launched.
+   */
+  private dispatchPausedExecutionResume;
+}
+//#endregion
+//#region subsystems/workflow-engine/src/cron-trigger-evaluator.d.ts
+/**
+ * Schedules and fires cron triggers for workflows on `'main-dev-machine'` role machines.
+ *
+ * On `init`, loads all workflow definitions with `cron` triggers and schedules
+ * them via croner. Subscribes to workflow CRUD events to keep the schedule
+ * index live.
+ *
+ * Each cron trigger fires `WorkflowSubjects.start` with the workflow ID and
+ * a `triggerPayload` containing the scheduled fire time.
+ *
+ * ## Role partitioning
+ *
+ * Only machines with role `'main-dev-machine'` should run this evaluator.
+ * Server-role machines rely on the relay-side `CronEvaluator` for routing.
+ * @example
+ * ```typescript
+ * if (machineRole === 'main-dev-machine') {
+ *   const evaluator = new CronTriggerEvaluator(bus);
+ *   await evaluator.init();
+ *   // ...on shutdown:
+ *   evaluator.destroy();
+ * }
+ * ```
+ */
+declare class CronTriggerEvaluator {
+  private readonly bus;
+  private readonly cleanupFns;
+  private initialized;
+  /**
+   * Active cron jobs keyed by `{workflowId}:{triggerIndex}`.
+   */
+  private readonly jobs;
+  /**
+   * @param bus - The shared bus instance
+   */
+  constructor(bus: IMakaioBus);
+  /**
+   * Initialize the evaluator.
+   *
+   * Idempotent: calling `init()` on an already-initialized evaluator is a no-op.
+   */
+  init(): Promise<void>;
+  /**
+   * Destroy the evaluator, stopping all cron jobs and removing all subscriptions.
+   *
+   * Idempotent: calling `destroy()` on a non-initialized evaluator is a no-op.
+   */
+  destroy(): void;
+  activeJobCount(): number;
+  /**
+   * Load all existing workflow definitions and schedule their cron triggers.
+   */
+  private loadExistingTriggers;
+  /**
+   * Schedule all `cron` triggers found in a workflow definition.
+   * @param workflow - Workflow definition to schedule
+   */
+  private scheduleWorkflow;
+  /**
+   * Stop and remove all cron jobs for a given workflow.
+   * @param workflowId - Workflow identifier to unschedule
+   */
+  private unscheduleWorkflow;
+  /**
+   * Stop and remove a single cron job by key.
+   * @param key - Job key (`{workflowId}:{triggerIndex}`)
+   */
+  private stopJob;
+  /**
+   * Stop all active cron jobs and clear the jobs map.
+   */
+  private stopAllJobs;
+  /**
+   * Fire a cron trigger by requesting workflow start.
+   *
+   * Errors are logged but not propagated — cron jobs are fire-and-forget.
+   * @param workflowId - Workflow to start
+   * @param triggerIndex - Index of the trigger that fired
+   */
+  private fireTrigger;
+}
+//#endregion
+//#region subsystems/workflow-engine/src/workflow-engine-service.d.ts
+/**
+ * Options for constructing a {@link WorkflowEngineService}.
+ *
+ * All fields are optional — when omitted the service uses the in-process
+ * workflow scheduler and default executor config.
+ */
+interface WorkflowEngineServiceOptions {
+  /**
+   * Workflow-level runner for dispatching full workflow executions to an
+   * isolated environment (worker thread pool, child process, container).
+   *
+   * When provided the executor delegates each new execution to this runner
+   * instead of running it in-process via the DAG scheduler.
+   * When omitted, execution falls back to the in-process DAG scheduler.
+   */
+  workflowRunner?: IWorkflowRunner;
+  /** Partial executor configuration merged with defaults. */
+  executorConfig?: Partial<ExecutorConfig>;
+  /**
+   * Injected execution attempt persistence port.
+   *
+   * Required when the workflow runner uses WorkerNode dispatch mode. The
+   * consuming host application provides the concrete implementation that owns
+   * durable attempt records and accept/duplicate/conflict/fence decisions.
+   *
+   * When omitted, the workflow engine operates without attempt tracking
+   * (framework-only, in-process, and Piscina modes).
+   */
+  executionAttemptRepository?: ExecutionAttemptRepository;
+  /**
+   * Pre-built execution attempt Authority.
+   *
+   * When provided, the service uses this Authority directly instead of
+   * constructing one from the repository. This allows the Authority to be
+   * shared with the runner that was constructed before this service.
+   *
+   * Takes precedence over `executionAttemptRepository` for Authority
+   * construction. When both are provided, the pre-built Authority is used
+   * and the repository is ignored.
+   */
+  executionAttemptAuthority?: ExecutionAttemptAuthority;
+  /** Host-owned resolvers that create portable specs for path-backed starts. */
+  workflowMaterializationSpecResolvers?: readonly WorkflowMaterializationSpecResolver[];
+}
+/**
+ * Workflow engine package service.
+ *
+ * Owns the boot lifecycle for the workflow executor and trigger evaluators so
+ * stored triggers become active during normal runtime package startup.
+ */
+declare class WorkflowEngineService extends BaseService {
+  private readonly workflowExecutor;
+  private readonly busEventTriggerEvaluator;
+  private readonly cronTriggerEvaluator;
+  private readonly attemptAuthority;
+  private readonly workspaceRootResolvers;
+  /**
+   * @param bus - Shared runtime bus.
+   * @param options - Optional workflow runner and executor config overrides.
+   */
+  constructor(bus: IMakaioBus, options?: WorkflowEngineServiceOptions);
+  /**
+   * Executor owned by this package service.
+   * @returns Workflow executor instance.
+   */
+  get executor(): WorkflowExecutor;
+  /**
+   * Execution attempt Authority owned by this package service.
+   *
+   * Present only when an {@link ExecutionAttemptRepository} was injected at
+   * construction time (WorkerNode dispatch mode). Returns `undefined` for
+   * framework-only, in-process, and Piscina modes.
+   * @returns Authority instance, or `undefined` when no repository is injected.
+   */
+  get executionAttemptAuthority(): ExecutionAttemptAuthority | undefined;
+  /**
+   * Register a named workflow success finalizer with the owned executor.
+   *
+   * Compiled workflow definitions opt into this registration through their
+   * immutable `successFinalizerId`; registration alone never changes ordinary
+   * workflow completion behavior.
+   * @param finalizerId - Stable lifecycle-finalizer identity.
+   * @returns Idempotent cleanup that unregisters this exact registration.
+   */
+  registerSuccessFinalizer(finalizerId: string): Promise<() => void>;
+  /**
+   * Accept a terminal result for a durable authority-owned runner execution.
+   * @param executionId - Durable authority-owned execution identity.
+   * @param result - Correlated terminal result returned by the runner.
+   * @returns The current durable status after acceptance.
+   */
+  acceptAuthorityRunnerResult(executionId: string, result: Parameters<WorkflowExecutor['acceptAuthorityRunnerResult']>[1]): ReturnType<WorkflowExecutor['acceptAuthorityRunnerResult']>;
+  /**
+   * Cron evaluator owned by this package service.
+   * @returns Cron trigger evaluator instance.
+   */
+  get cronTriggers(): CronTriggerEvaluator;
+  /**
+   * Set the trigger type registry used by executor request handlers.
+   * @param registry - Trigger type registry instance.
+   */
+  setTriggerTypeRegistry(registry: IWorkflowTriggerTypeRegistry): void;
+  /**
+   * Retrieve the executor trigger type registry.
+   * @returns Trigger type registry, or `undefined` when none is set.
+   */
+  getTriggerTypeRegistry(): IWorkflowTriggerTypeRegistry | undefined;
+  /**
+   * Register a host resolver used to freeze a path-backed workflow's workspace
+   * reference before the durable run context is written.
+   * @param resolver - Host-owned resolver.
+   * @returns Idempotent cleanup that unregisters this resolver.
+   */
+  registerWorkflowMaterializationSpecResolver(resolver: WorkflowMaterializationSpecResolver): () => void;
+  /**
+   * Register a host-owned workspace-root resolver.
+   * @param resolver - Resolver to consult before the boot-level fallback resolver.
+   * @returns Idempotent cleanup that unregisters this exact resolver.
+   */
+  registerWorkspaceRootResolver(resolver: WorkflowWorkspaceRootResolver): () => void;
+  /**
+   * Resolve a portable workspace identifier through registered host resolvers.
+   * @param workspaceId - Portable workspace identifier from a materialization spec.
+   * @returns The first registered root, or `undefined` when no resolver recognizes the identifier.
+   */
+  resolveWorkspaceRoot(workspaceId: string): Promise<string | undefined>;
+  /**
+   * Initialize executor handlers before trigger evaluators can fire starts.
+   * @returns Promise that resolves once all child services are initialized.
+   */
+  protected onInit(): Promise<void>;
+  /**
+   * Tear down child services in reverse boot order.
+   * @returns Promise that resolves once all child services are destroyed.
+   */
+  private destroyOwnedServices;
+}
+//#endregion
+//#region subsystems/workflow-engine/src/package.d.ts
+/** Typed package token for retrieving the workflow engine package service. */
+declare const WorkflowEngineToken: _$_makaio_contracts0.ExtensionToken<WorkflowEngineService>;
+/**
+ * Create a workflow engine package manifest with optional runtime overrides.
+ *
+ * The returned manifest registers the `WorkflowEngineService` as the package
+ * service, wires Drizzle storage handlers, and forwards the provided options
+ * to the executor so that composition roots can inject a workflow-level runner
+ * or executor configuration (e.g. busUrl, busAuth, platformDefaults).
+ * @param options - Optional workflow runner and executor config overrides.
+ * @returns A `MakaioNodeExtension` manifest for the workflow engine subsystem.
+ */
+declare function createWorkflowEnginePackage(options?: WorkflowEngineServiceOptions): MakaioNodeExtension<IMakaioBus>;
+/**
+ * Default workflow engine package manifest (no runtime overrides).
+ *
+ * Equivalent to `createWorkflowEnginePackage()` with no arguments. Preserved
+ * for existing consumers that reference the static constant directly.
+ */
+declare const workflowEnginePackage: MakaioNodeExtension<IMakaioBus>;
+//#endregion
+export { WorkflowEngineServiceOptions as a, WorkflowMaterializationSpecResolution as c, registerDrizzleWorkflowStorage as d, WorkflowEngineService as i, WorkflowMaterializationSpecResolver as l, createWorkflowEnginePackage as n, WorkflowExecutor as o, workflowEnginePackage as r, ExecutionAttemptAuthority as s, WorkflowEngineToken as t, WorkflowWorkspaceRootResolver as u };