@tasker-systems/tasker 0.1.1 → 0.1.2

package/README.md

@@ -0,0 +1,118 @@
+# @tasker-systems/tasker
+
+TypeScript worker for the Tasker workflow orchestration system. Supports Bun (native FFI), Node.js (via koffi), and Deno runtimes.
+
+## Status
+
+Production ready. TypeScript worker bindings provide full step handler execution via FFI to the shared Rust `tasker-worker` infrastructure.
+
+## Installation
+
+```bash
+# Bun (recommended - native FFI support)
+bun add @tasker-systems/tasker
+
+# Node.js (requires koffi for FFI)
+npm install @tasker-systems/tasker koffi
+```
+
+## Quick Start
+
+```typescript
+import { TaskerWorker } from "@tasker-systems/tasker";
+
+const worker = new TaskerWorker({
+  workerName: "my-worker",
+  namespaces: ["default"],
+});
+
+// Register a step handler
+worker.registerHandler("process_payment", async (step) => {
+  const result = await processPayment(step.context);
+  return { status: "complete", data: result };
+});
+
+// Start the worker
+await worker.start();
+```
+
+## Development
+
+### Prerequisites
+
+- Bun 1.0+ (recommended) or Node.js 18+
+- Rust 1.70+ (for building the FFI library)
+
+### Setup
+
+```bash
+# Install dependencies
+bun install
+
+# Build TypeScript
+bun run build
+
+# Run tests
+bun test
+
+# Type checking
+bun run typecheck
+
+# Linting
+bun run check
+```
+
+### Building the FFI Library
+
+```bash
+# Build the Rust FFI shared library
+cargo build --release -p tasker-worker-ts
+
+# The library will be at target/release/libtasker_worker_ts.{dylib,so,dll}
+```
+
+## Project Structure
+
+```
+workers/typescript/
+├── src/                  # TypeScript source
+│   ├── bootstrap/        # Worker initialization
+│   ├── events/           # Event system integration
+│   ├── ffi/              # FFI bindings to Rust
+│   ├── handler/          # Step handler base classes
+│   ├── logging/          # Structured logging (pino)
+│   ├── registry/         # Handler registry
+│   ├── server/           # HTTP/gRPC server
+│   ├── subscriber/       # Queue subscriber
+│   ├── types/            # Type definitions
+│   └── index.ts          # Package entry point
+├── src-rust/             # Rust FFI source
+│   └── lib.rs            # Neon/FFI module
+├── tests/                # Test suite
+├── Cargo.toml            # Rust crate configuration
+├── package.json          # npm package configuration
+├── tsconfig.json         # TypeScript configuration
+└── biome.json            # Linting configuration
+```
+
+## Technology Stack
+
+- **FFI Layer**: Bun native FFI / koffi (Node.js)
+- **Build Tool**: tsup
+- **Runtime**: Bun, Node.js 18+, or Deno
+- **Testing**: Bun test runner
+- **Linting**: Biome
+- **Logging**: pino
+- **Events**: eventemitter3
+
+## Runtime Support
+
+| Runtime | FFI Mechanism | Status |
+|---------|---------------|--------|
+| Bun | Native `bun:ffi` | Recommended |
+| Node.js | koffi | Supported |
+| Deno | `Deno.dlopen` | Experimental |
+
+## License
+
+MIT

package/dist/events/index.d.ts

@@ -1,3 +1,3 @@
-export { y as ErrorCallback, n as EventName, o as EventNames, d as EventPoller, z as EventPollerConfig, f as EventSystem, F as EventSystemConfig, G as EventSystemStats, A as MetricsCallback, p as MetricsEventName, q as MetricsEventNames, M as MetricsPayload, P as PollerCyclePayload, r as PollerEventName, s as PollerEventNames, C as PollerState, g as StepCompletionSentPayload, D as StepEventCallback, t as StepEventName, u as StepEventNames, h as StepExecutionCompletedPayload, i as StepExecutionFailedPayload, j as StepExecutionReceivedPayload, k as StepExecutionStartedPayload, T as TaskerEventEmitter, l as TaskerEventMap, W as WorkerErrorPayload, v as WorkerEventName, w as WorkerEventNames, m as WorkerEventPayload, x as createEventPoller } from '../index-B3BcknlZ.js';
+export { y as ErrorCallback, n as EventName, o as EventNames, d as EventPoller, z as EventPollerConfig, f as EventSystem, F as EventSystemConfig, G as EventSystemStats, A as MetricsCallback, p as MetricsEventName, q as MetricsEventNames, M as MetricsPayload, P as PollerCyclePayload, r as PollerEventName, s as PollerEventNames, C as PollerState, g as StepCompletionSentPayload, D as StepEventCallback, t as StepEventName, u as StepEventNames, h as StepExecutionCompletedPayload, i as StepExecutionFailedPayload, j as StepExecutionReceivedPayload, k as StepExecutionStartedPayload, T as TaskerEventEmitter, l as TaskerEventMap, W as WorkerErrorPayload, v as WorkerEventName, w as WorkerEventNames, m as WorkerEventPayload, x as createEventPoller } from '../index-CTl8lGpU.js';
 import 'eventemitter3';
-import '../runtime-interface-CE4viUt7.js';
+import '../runtime-interface-D940vUzy.js';

package/dist/ffi/index.d.ts

@@ -1,139 +1,5 @@
-import { B as BaseTaskerRuntime, a as BootstrapConfig, b as BootstrapResult, W as WorkerStatus, q as StopResult, l as FfiStepEvent, F as FfiDomainEvent, p as StepExecutionResult, t as CheckpointYieldData, k as FfiDispatchMetrics, L as LogFields, d as ClientResult, T as TaskerRuntime } from '../runtime-interface-CE4viUt7.js';
-export { D as DependencyResult, u as FfiDomainEventMetadata, m as HandlerDefinition, O as OrchestrationMetadata, R as RetryConfiguration, S as StepDefinition, n as StepExecutionError, o as StepExecutionMetadata, r as Task, s as WorkflowStep } from '../runtime-interface-CE4viUt7.js';
-
-/**
- * Node.js FFI runtime adapter using koffi.
- *
- * This adapter uses the koffi package to interface with the Rust native library.
- * Koffi is a modern, actively maintained FFI library with prebuilt binaries.
- *
- * Install: npm install koffi
- */
-
-/**
- * Node.js FFI runtime implementation using koffi
- */
-declare class NodeRuntime extends BaseTaskerRuntime {
-    readonly name: string;
-    private lib;
-    private koffi;
-    get isLoaded(): boolean;
-    load(libraryPath: string): Promise<void>;
-    unload(): void;
-    private ensureLoaded;
-    /**
-     * Read a C string from a pointer and free the Rust-allocated memory.
-     *
-     * Uses koffi.decode with 'char' type and -1 length for null-terminated strings.
-     */
-    private readAndFreeRustString;
-    getVersion(): string;
-    getRustVersion(): string;
-    healthCheck(): boolean;
-    bootstrapWorker(config?: BootstrapConfig): BootstrapResult;
-    isWorkerRunning(): boolean;
-    getWorkerStatus(): WorkerStatus;
-    stopWorker(): StopResult;
-    transitionToGracefulShutdown(): StopResult;
-    pollStepEvents(): FfiStepEvent | null;
-    pollInProcessEvents(): FfiDomainEvent | null;
-    completeStepEvent(eventId: string, result: StepExecutionResult): boolean;
-    checkpointYieldStepEvent(eventId: string, checkpointData: CheckpointYieldData): boolean;
-    getFfiDispatchMetrics(): FfiDispatchMetrics;
-    checkStarvationWarnings(): void;
-    cleanupTimeouts(): void;
-    logError(message: string, fields?: LogFields): void;
-    logWarn(message: string, fields?: LogFields): void;
-    logInfo(message: string, fields?: LogFields): void;
-    logDebug(message: string, fields?: LogFields): void;
-    logTrace(message: string, fields?: LogFields): void;
-    private parseClientResult;
-    clientCreateTask(requestJson: string): ClientResult;
-    clientGetTask(taskUuid: string): ClientResult;
-    clientListTasks(paramsJson: string): ClientResult;
-    clientCancelTask(taskUuid: string): ClientResult;
-    clientListTaskSteps(taskUuid: string): ClientResult;
-    clientGetStep(taskUuid: string, stepUuid: string): ClientResult;
-    clientGetStepAuditHistory(taskUuid: string, stepUuid: string): ClientResult;
-    clientHealthCheck(): ClientResult;
-}
-
-/**
- * Bun FFI runtime adapter using koffi (via Node-API).
- *
- * Bun supports Node-API modules natively, so we use koffi (the same FFI
- * library as NodeRuntime) rather than bun:ffi. This gives us:
- * - Stable, well-tested string/pointer handling
- * - Identical behavior across Node.js and Bun
- * - No manual Buffer→pointer conversion bugs
- *
- * See: https://bun.sh/docs/runtime/node-api
- */
-
-/**
- * Bun FFI runtime implementation using koffi (Node-API).
- *
- * Extends NodeRuntime since both use koffi for FFI. The only difference
- * is the runtime name identifier used for logging and diagnostics.
- */
-declare class BunRuntime extends NodeRuntime {
-    readonly name = "bun";
-}
-
-/**
- * Deno FFI runtime adapter using Deno.dlopen.
- *
- * This adapter uses Deno's built-in FFI to interface with the Rust native library.
- * It requires --unstable-ffi and --allow-ffi flags.
- */
-
-/**
- * Deno FFI runtime implementation using Deno.dlopen
- */
-declare class DenoRuntime extends BaseTaskerRuntime {
-    readonly name = "deno";
-    private lib;
-    private encoder;
-    get isLoaded(): boolean;
-    load(libraryPath: string): Promise<void>;
-    unload(): void;
-    private ensureLoaded;
-    /**
-     * Creates a null-terminated C string buffer.
-     * With 'buffer' FFI type, we return Uint8Array directly.
-     */
-    private toCString;
-    private fromCString;
-    getVersion(): string;
-    getRustVersion(): string;
-    healthCheck(): boolean;
-    bootstrapWorker(config?: BootstrapConfig): BootstrapResult;
-    isWorkerRunning(): boolean;
-    getWorkerStatus(): WorkerStatus;
-    stopWorker(): StopResult;
-    transitionToGracefulShutdown(): StopResult;
-    pollStepEvents(): FfiStepEvent | null;
-    pollInProcessEvents(): FfiDomainEvent | null;
-    completeStepEvent(eventId: string, result: StepExecutionResult): boolean;
-    checkpointYieldStepEvent(eventId: string, checkpointData: CheckpointYieldData): boolean;
-    getFfiDispatchMetrics(): FfiDispatchMetrics;
-    checkStarvationWarnings(): void;
-    cleanupTimeouts(): void;
-    logError(message: string, fields?: LogFields): void;
-    logWarn(message: string, fields?: LogFields): void;
-    logInfo(message: string, fields?: LogFields): void;
-    logDebug(message: string, fields?: LogFields): void;
-    logTrace(message: string, fields?: LogFields): void;
-    private parseClientResult;
-    clientCreateTask(requestJson: string): ClientResult;
-    clientGetTask(taskUuid: string): ClientResult;
-    clientListTasks(paramsJson: string): ClientResult;
-    clientCancelTask(taskUuid: string): ClientResult;
-    clientListTaskSteps(taskUuid: string): ClientResult;
-    clientGetStep(taskUuid: string, stepUuid: string): ClientResult;
-    clientGetStepAuditHistory(taskUuid: string, stepUuid: string): ClientResult;
-    clientHealthCheck(): ClientResult;
-}
+import { T as TaskerRuntime, B as BaseTaskerRuntime, e as BootstrapConfig, f as BootstrapResult, W as WorkerStatus, q as StopResult, l as FfiStepEvent, F as FfiDomainEvent, p as StepExecutionResult, t as CheckpointYieldData, k as FfiDispatchMetrics, L as LogFields, h as ClientResult } from '../runtime-interface-D940vUzy.js';
+export { D as DependencyResult, u as FfiDomainEventMetadata, m as HandlerDefinition, O as OrchestrationMetadata, R as RetryConfiguration, S as StepDefinition, n as StepExecutionError, o as StepExecutionMetadata, r as Task, s as WorkflowStep } from '../runtime-interface-D940vUzy.js';
 
 /**
  * Runtime detection for TypeScript/JavaScript workers.
@@ -305,4 +171,138 @@ declare class FfiLayer {
     private createRuntime;
 }
 
+/**
+ * Node.js FFI runtime adapter using koffi.
+ *
+ * This adapter uses the koffi package to interface with the Rust native library.
+ * Koffi is a modern, actively maintained FFI library with prebuilt binaries.
+ *
+ * Install: npm install koffi
+ */
+
+/**
+ * Node.js FFI runtime implementation using koffi
+ */
+declare class NodeRuntime extends BaseTaskerRuntime {
+    readonly name: string;
+    private lib;
+    private koffi;
+    get isLoaded(): boolean;
+    load(libraryPath: string): Promise<void>;
+    unload(): void;
+    private ensureLoaded;
+    /**
+     * Read a C string from a pointer and free the Rust-allocated memory.
+     *
+     * Uses koffi.decode with 'char' type and -1 length for null-terminated strings.
+     */
+    private readAndFreeRustString;
+    getVersion(): string;
+    getRustVersion(): string;
+    healthCheck(): boolean;
+    bootstrapWorker(config?: BootstrapConfig): BootstrapResult;
+    isWorkerRunning(): boolean;
+    getWorkerStatus(): WorkerStatus;
+    stopWorker(): StopResult;
+    transitionToGracefulShutdown(): StopResult;
+    pollStepEvents(): FfiStepEvent | null;
+    pollInProcessEvents(): FfiDomainEvent | null;
+    completeStepEvent(eventId: string, result: StepExecutionResult): boolean;
+    checkpointYieldStepEvent(eventId: string, checkpointData: CheckpointYieldData): boolean;
+    getFfiDispatchMetrics(): FfiDispatchMetrics;
+    checkStarvationWarnings(): void;
+    cleanupTimeouts(): void;
+    logError(message: string, fields?: LogFields): void;
+    logWarn(message: string, fields?: LogFields): void;
+    logInfo(message: string, fields?: LogFields): void;
+    logDebug(message: string, fields?: LogFields): void;
+    logTrace(message: string, fields?: LogFields): void;
+    private parseClientResult;
+    clientCreateTask(requestJson: string): ClientResult;
+    clientGetTask(taskUuid: string): ClientResult;
+    clientListTasks(paramsJson: string): ClientResult;
+    clientCancelTask(taskUuid: string): ClientResult;
+    clientListTaskSteps(taskUuid: string): ClientResult;
+    clientGetStep(taskUuid: string, stepUuid: string): ClientResult;
+    clientGetStepAuditHistory(taskUuid: string, stepUuid: string): ClientResult;
+    clientHealthCheck(): ClientResult;
+}
+
+/**
+ * Bun FFI runtime adapter using koffi (via Node-API).
+ *
+ * Bun supports Node-API modules natively, so we use koffi (the same FFI
+ * library as NodeRuntime) rather than bun:ffi. This gives us:
+ * - Stable, well-tested string/pointer handling
+ * - Identical behavior across Node.js and Bun
+ * - No manual Buffer→pointer conversion bugs
+ *
+ * See: https://bun.sh/docs/runtime/node-api
+ */
+
+/**
+ * Bun FFI runtime implementation using koffi (Node-API).
+ *
+ * Extends NodeRuntime since both use koffi for FFI. The only difference
+ * is the runtime name identifier used for logging and diagnostics.
+ */
+declare class BunRuntime extends NodeRuntime {
+    readonly name = "bun";
+}
+
+/**
+ * Deno FFI runtime adapter using Deno.dlopen.
+ *
+ * This adapter uses Deno's built-in FFI to interface with the Rust native library.
+ * It requires --unstable-ffi and --allow-ffi flags.
+ */
+
+/**
+ * Deno FFI runtime implementation using Deno.dlopen
+ */
+declare class DenoRuntime extends BaseTaskerRuntime {
+    readonly name = "deno";
+    private lib;
+    private encoder;
+    get isLoaded(): boolean;
+    load(libraryPath: string): Promise<void>;
+    unload(): void;
+    private ensureLoaded;
+    /**
+     * Creates a null-terminated C string buffer.
+     * With 'buffer' FFI type, we return Uint8Array directly.
+     */
+    private toCString;
+    private fromCString;
+    getVersion(): string;
+    getRustVersion(): string;
+    healthCheck(): boolean;
+    bootstrapWorker(config?: BootstrapConfig): BootstrapResult;
+    isWorkerRunning(): boolean;
+    getWorkerStatus(): WorkerStatus;
+    stopWorker(): StopResult;
+    transitionToGracefulShutdown(): StopResult;
+    pollStepEvents(): FfiStepEvent | null;
+    pollInProcessEvents(): FfiDomainEvent | null;
+    completeStepEvent(eventId: string, result: StepExecutionResult): boolean;
+    checkpointYieldStepEvent(eventId: string, checkpointData: CheckpointYieldData): boolean;
+    getFfiDispatchMetrics(): FfiDispatchMetrics;
+    checkStarvationWarnings(): void;
+    cleanupTimeouts(): void;
+    logError(message: string, fields?: LogFields): void;
+    logWarn(message: string, fields?: LogFields): void;
+    logInfo(message: string, fields?: LogFields): void;
+    logDebug(message: string, fields?: LogFields): void;
+    logTrace(message: string, fields?: LogFields): void;
+    private parseClientResult;
+    clientCreateTask(requestJson: string): ClientResult;
+    clientGetTask(taskUuid: string): ClientResult;
+    clientListTasks(paramsJson: string): ClientResult;
+    clientCancelTask(taskUuid: string): ClientResult;
+    clientListTaskSteps(taskUuid: string): ClientResult;
+    clientGetStep(taskUuid: string, stepUuid: string): ClientResult;
+    clientGetStepAuditHistory(taskUuid: string, stepUuid: string): ClientResult;
+    clientHealthCheck(): ClientResult;
+}
+
 export { BaseTaskerRuntime, BootstrapConfig, BootstrapResult, BunRuntime, DenoRuntime, FfiDispatchMetrics, FfiDomainEvent, FfiLayer, type FfiLayerConfig, FfiStepEvent, LogFields, NodeRuntime, type RuntimeInfo, type RuntimeType, StepExecutionResult, StopResult, TaskerRuntime, WorkerStatus, detectRuntime, getLibraryPath, getRuntimeInfo, isBun, isDeno, isNode };

package/dist/{index-B3BcknlZ.d.ts → index-CTl8lGpU.d.ts}

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'eventemitter3';
-import { l as FfiStepEvent, p as StepExecutionResult, k as FfiDispatchMetrics, T as TaskerRuntime } from './runtime-interface-CE4viUt7.js';
+import { l as FfiStepEvent, p as StepExecutionResult, k as FfiDispatchMetrics, T as TaskerRuntime } from './runtime-interface-D940vUzy.js';
 
 /**
  * Event emitter for TypeScript workers.

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { T as TaskerRuntime, F as FfiDomainEvent, H as HandlerDefinitionDto } from './runtime-interface-CE4viUt7.js';
-export { B as BaseTaskerRuntime, C as ClientHealthResponse, c as ClientPaginationInfo, d as ClientResult, e as ClientStepAuditResponse, f as ClientStepReadiness, g as ClientStepResponse, h as ClientTaskListResponse, i as ClientTaskRequest, j as ClientTaskResponse, D as DependencyResult, a as FfiBootstrapConfig, b as FfiBootstrapResult, k as FfiDispatchMetrics, L as FfiLogFields, l as FfiStepEvent, q as FfiStopResult, W as FfiWorkerStatus, m as HandlerDefinition, O as OrchestrationMetadata, R as RetryConfiguration, S as StepDefinition, n as StepExecutionError, o as StepExecutionMetadata, p as StepExecutionResult, r as Task, s as WorkflowStep } from './runtime-interface-CE4viUt7.js';
-import { S as StepHandlerResult, a as StepHandler, B as BatchWorkerConfig, b as StepContext, E as ExecutableHandler, c as StepHandlerClass, T as TaskerEventEmitter, d as EventPoller, e as StepExecutionSubscriber, f as EventSystem } from './index-B3BcknlZ.js';
-export { y as ErrorCallback, I as ErrorType, n as EventName, o as EventNames, z as EventPollerConfig, F as EventSystemConfig, G as EventSystemStats, A as MetricsCallback, p as MetricsEventName, q as MetricsEventNames, M as MetricsPayload, P as PollerCyclePayload, r as PollerEventName, s as PollerEventNames, C as PollerState, g as StepCompletionSentPayload, L as StepContextParams, D as StepEventCallback, t as StepEventName, u as StepEventNames, h as StepExecutionCompletedPayload, i as StepExecutionFailedPayload, j as StepExecutionReceivedPayload, k as StepExecutionStartedPayload, H as StepExecutionSubscriberConfig, N as StepHandlerResultParams, l as TaskerEventMap, W as WorkerErrorPayload, v as WorkerEventName, w as WorkerEventNames, m as WorkerEventPayload, x as createEventPoller, J as isStandardErrorType, K as isTypicallyRetryable } from './index-B3BcknlZ.js';
-import { FfiLayerConfig } from './ffi/index.js';
-export { BunRuntime, DenoRuntime, FfiLayer, NodeRuntime, RuntimeInfo, RuntimeType, detectRuntime, getLibraryPath, getRuntimeInfo, isBun, isDeno, isNode } from './ffi/index.js';
+import { T as TaskerRuntime, C as ClientTaskResponse, a as ClientTaskListResponse, b as ClientStepResponse, c as ClientStepAuditResponse, d as ClientHealthResponse, F as FfiDomainEvent, H as HandlerDefinitionDto } from './runtime-interface-D940vUzy.js';
+export { B as BaseTaskerRuntime, g as ClientPaginationInfo, h as ClientResult, i as ClientStepReadiness, j as ClientTaskRequest, D as DependencyResult, e as FfiBootstrapConfig, f as FfiBootstrapResult, k as FfiDispatchMetrics, L as FfiLogFields, l as FfiStepEvent, q as FfiStopResult, W as FfiWorkerStatus, m as HandlerDefinition, O as OrchestrationMetadata, R as RetryConfiguration, S as StepDefinition, n as StepExecutionError, o as StepExecutionMetadata, p as StepExecutionResult, r as Task, s as WorkflowStep } from './runtime-interface-D940vUzy.js';
+import { FfiLayer, FfiLayerConfig } from './ffi/index.js';
+export { BunRuntime, DenoRuntime, NodeRuntime, RuntimeInfo, RuntimeType, detectRuntime, getLibraryPath, getRuntimeInfo, isBun, isDeno, isNode } from './ffi/index.js';
+import { S as StepHandlerResult, a as StepHandler, B as BatchWorkerConfig, b as StepContext, E as ExecutableHandler, c as StepHandlerClass, T as TaskerEventEmitter, d as EventPoller, e as StepExecutionSubscriber, f as EventSystem } from './index-CTl8lGpU.js';
+export { y as ErrorCallback, I as ErrorType, n as EventName, o as EventNames, z as EventPollerConfig, F as EventSystemConfig, G as EventSystemStats, A as MetricsCallback, p as MetricsEventName, q as MetricsEventNames, M as MetricsPayload, P as PollerCyclePayload, r as PollerEventName, s as PollerEventNames, C as PollerState, g as StepCompletionSentPayload, L as StepContextParams, D as StepEventCallback, t as StepEventName, u as StepEventNames, h as StepExecutionCompletedPayload, i as StepExecutionFailedPayload, j as StepExecutionReceivedPayload, k as StepExecutionStartedPayload, H as StepExecutionSubscriberConfig, N as StepHandlerResultParams, l as TaskerEventMap, W as WorkerErrorPayload, v as WorkerEventName, w as WorkerEventNames, m as WorkerEventPayload, x as createEventPoller, J as isStandardErrorType, K as isTypicallyRetryable } from './index-CTl8lGpU.js';
 import { Logger } from 'pino';
 import 'eventemitter3';
 
@@ -225,6 +225,166 @@ declare function getRustVersion(runtime?: TaskerRuntime): string;
  */
 declare function healthCheck(runtime?: TaskerRuntime): boolean;
 
+/**
+ * High-level client wrapper for orchestration API operations.
+ *
+ * The raw FFI exposes `runtime.clientCreateTask(json)` and similar methods
+ * that require callers to construct complete JSON request strings with all
+ * required fields and return untyped `ClientResult` envelopes.
+ *
+ * This module provides a `TaskerClient` class with typed methods, sensible
+ * defaults, and proper error handling.
+ *
+ * @example
+ * ```typescript
+ * import { FfiLayer, TaskerClient } from '@tasker-systems/tasker';
+ *
+ * const ffiLayer = new FfiLayer();
+ * await ffiLayer.load();
+ * const client = new TaskerClient(ffiLayer);
+ *
+ * const task = client.createTask({ name: 'process_order', namespace: 'ecommerce' });
+ * console.log(task.task_uuid);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for creating a task.
+ *
+ * Only `name` is required; all other fields have sensible defaults.
+ */
+interface CreateTaskOptions {
+    /** Named task template name */
+    name: string;
+    /** Task namespace (default: 'default') */
+    namespace?: string;
+    /** Workflow context passed to step handlers (default: {}) */
+    context?: Record<string, unknown>;
+    /** Template version (default: '1.0.0') */
+    version?: string;
+    /** Who initiated the request (default: 'tasker-core-typescript') */
+    initiator?: string;
+    /** Originating system (default: 'tasker-core') */
+    sourceSystem?: string;
+    /** Reason for creating the task (default: 'Task requested') */
+    reason?: string;
+    /** Optional tags */
+    tags?: string[];
+    /** Optional priority */
+    priority?: number | null;
+    /** Optional correlation ID (auto-generated if not provided) */
+    correlationId?: string;
+    /** Optional parent correlation ID */
+    parentCorrelationId?: string | null;
+    /** Optional idempotency key */
+    idempotencyKey?: string | null;
+}
+/**
+ * Options for listing tasks.
+ */
+interface ListTasksOptions {
+    /** Maximum number of results (default: 50) */
+    limit?: number;
+    /** Pagination offset (default: 0) */
+    offset?: number;
+    /** Filter by namespace */
+    namespace?: string;
+    /** Filter by status */
+    status?: string;
+}
+/**
+ * Error thrown when a client operation fails.
+ */
+declare class TaskerClientError extends Error {
+    /** Whether the error is potentially recoverable */
+    readonly recoverable: boolean;
+    constructor(message: string, recoverable?: boolean);
+}
+/**
+ * High-level client for orchestration API operations.
+ *
+ * Wraps the raw FFI methods with typed interfaces, sensible defaults,
+ * and proper error handling via `TaskerClientError`.
+ */
+declare class TaskerClient {
+    private readonly ffiLayer;
+    constructor(ffiLayer: FfiLayer);
+    /**
+     * Create a task via the orchestration API.
+     *
+     * @param options - Task creation options (only `name` is required)
+     * @returns Typed task response
+     * @throws TaskerClientError if the operation fails
+     */
+    createTask(options: CreateTaskOptions): ClientTaskResponse;
+    /**
+     * Get a task by UUID.
+     *
+     * @param taskUuid - The task UUID
+     * @returns Typed task response
+     * @throws TaskerClientError if the operation fails
+     */
+    getTask(taskUuid: string): ClientTaskResponse;
+    /**
+     * List tasks with optional filtering and pagination.
+     *
+     * @param options - Filtering and pagination options
+     * @returns Typed task list response with pagination
+     * @throws TaskerClientError if the operation fails
+     */
+    listTasks(options?: ListTasksOptions): ClientTaskListResponse;
+    /**
+     * Cancel a task by UUID.
+     *
+     * @param taskUuid - The task UUID
+     * @throws TaskerClientError if the operation fails
+     */
+    cancelTask(taskUuid: string): void;
+    /**
+     * List workflow steps for a task.
+     *
+     * @param taskUuid - The task UUID
+     * @returns Array of typed step responses
+     * @throws TaskerClientError if the operation fails
+     */
+    listTaskSteps(taskUuid: string): ClientStepResponse[];
+    /**
+     * Get a specific workflow step.
+     *
+     * @param taskUuid - The task UUID
+     * @param stepUuid - The step UUID
+     * @returns Typed step response
+     * @throws TaskerClientError if the operation fails
+     */
+    getStep(taskUuid: string, stepUuid: string): ClientStepResponse;
+    /**
+     * Get audit history for a workflow step.
+     *
+     * @param taskUuid - The task UUID
+     * @param stepUuid - The step UUID
+     * @returns Array of typed audit history entries
+     * @throws TaskerClientError if the operation fails
+     */
+    getStepAuditHistory(taskUuid: string, stepUuid: string): ClientStepAuditResponse[];
+    /**
+     * Check orchestration API health.
+     *
+     * @returns Typed health response
+     * @throws TaskerClientError if the operation fails
+     */
+    healthCheck(): ClientHealthResponse;
+    /**
+     * Unwrap a ClientResult envelope, throwing on error.
+     */
+    private unwrap;
+    /**
+     * Get the FFI runtime from the layer.
+     */
+    private getRuntime;
+}
+
 /**
  * API mixin for HTTP functionality.
  *
@@ -4010,4 +4170,4 @@ declare class WorkerServer {
     private cleanupOnError;
 }
 
-export { type APICapable, APIMixin, ApiHandler, ApiResponse, BasePublisher, type BaseResolver, BaseSubscriber, type BatchAggregationResult, type BatchAnalyzerOutcome, type BatchMetadata, type BatchProcessingOutcome, type BatchWorkerContext, type BatchWorkerOutcome, type Batchable, BatchableMixin, type BootstrapConfig, type BootstrapResult, ClassLookupResolver, type CreateBatchesOutcome, type CursorConfig, type DecisionCapable, DecisionHandler, DecisionMixin, type DecisionPointOutcome, DecisionType, DefaultPublisher, type DomainEvent, type DomainEventCallback, type DomainEventErrorCallback, type DomainEventMetadata, type DomainEventPollerConfig, DuplicatePublisherError, type EventDeclaration, EventPoller, EventSystem, ExecutableHandler, ExplicitMappingResolver, type FailureStrategy, FfiLayerConfig, type HandlerEntry, type HandlerFactory, HandlerRegistry, type HandlerSpec, HandlerSystem, InProcessDomainEventPoller, type LogFields, MethodDispatchError, MethodDispatchWrapper, type NoBatchesOutcome, NoResolverMatchError, type PollerStats, type PublishContext, PublisherNotFoundError, PublisherRegistry, PublisherValidationError, RegistryFrozenError, RegistryResolver, type RegistryResolverStatic, ResolutionError, ResolverChain, type ResolverConfig, ResolverNotFoundError, type RustBatchWorkerInputs, type RustCursorConfig, type ServerComponents, type HealthCheckResult as ServerHealthCheckResult, type ServerState, type ServerStatus, ShutdownController, type ShutdownHandler, StepContext, type StepEventContext, StepExecutionSubscriber, StepHandler, StepHandlerClass, StepHandlerResult, type StepResult, type StopResult, type SubscriberClass, SubscriberRegistry, type SubscriberStats, TaskerEventEmitter, TaskerRuntime, WorkerServer, type WorkerServerConfig, type WorkerStatus, aggregateBatchResults, applyAPI, applyBatchable, applyDecision, bootstrapWorker, createBatchWorkerContext, createBatches, createDomainEvent, createFfiPollAdapter, createLogger, createStepEventContext, effectiveMethod, ffiEventToDomainEvent, fromCallable, fromDto, getRustVersion, getVersion, getWorkerStatus, hasResolverHint, healthCheck, isCreateBatches, isNoBatches, isWorkerRunning, logDebug, logError, logInfo, logTrace, logWarn, noBatches, normalizeToDefinition, stopWorker, transitionToGracefulShutdown, usesMethodDispatch };
+export { type APICapable, APIMixin, ApiHandler, ApiResponse, BasePublisher, type BaseResolver, BaseSubscriber, type BatchAggregationResult, type BatchAnalyzerOutcome, type BatchMetadata, type BatchProcessingOutcome, type BatchWorkerContext, type BatchWorkerOutcome, type Batchable, BatchableMixin, type BootstrapConfig, type BootstrapResult, ClassLookupResolver, ClientHealthResponse, ClientStepAuditResponse, ClientStepResponse, ClientTaskListResponse, ClientTaskResponse, type CreateBatchesOutcome, type CreateTaskOptions, type CursorConfig, type DecisionCapable, DecisionHandler, DecisionMixin, type DecisionPointOutcome, DecisionType, DefaultPublisher, type DomainEvent, type DomainEventCallback, type DomainEventErrorCallback, type DomainEventMetadata, type DomainEventPollerConfig, DuplicatePublisherError, type EventDeclaration, EventPoller, EventSystem, ExecutableHandler, ExplicitMappingResolver, type FailureStrategy, FfiLayer, FfiLayerConfig, type HandlerEntry, type HandlerFactory, HandlerRegistry, type HandlerSpec, HandlerSystem, InProcessDomainEventPoller, type ListTasksOptions, type LogFields, MethodDispatchError, MethodDispatchWrapper, type NoBatchesOutcome, NoResolverMatchError, type PollerStats, type PublishContext, PublisherNotFoundError, PublisherRegistry, PublisherValidationError, RegistryFrozenError, RegistryResolver, type RegistryResolverStatic, ResolutionError, ResolverChain, type ResolverConfig, ResolverNotFoundError, type RustBatchWorkerInputs, type RustCursorConfig, type ServerComponents, type HealthCheckResult as ServerHealthCheckResult, type ServerState, type ServerStatus, ShutdownController, type ShutdownHandler, StepContext, type StepEventContext, StepExecutionSubscriber, StepHandler, StepHandlerClass, StepHandlerResult, type StepResult, type StopResult, type SubscriberClass, SubscriberRegistry, type SubscriberStats, TaskerClient, TaskerClientError, TaskerEventEmitter, TaskerRuntime, WorkerServer, type WorkerServerConfig, type WorkerStatus, aggregateBatchResults, applyAPI, applyBatchable, applyDecision, bootstrapWorker, createBatchWorkerContext, createBatches, createDomainEvent, createFfiPollAdapter, createLogger, createStepEventContext, effectiveMethod, ffiEventToDomainEvent, fromCallable, fromDto, getRustVersion, getVersion, getWorkerStatus, hasResolverHint, healthCheck, isCreateBatches, isNoBatches, isWorkerRunning, logDebug, logError, logInfo, logTrace, logWarn, noBatches, normalizeToDefinition, stopWorker, transitionToGracefulShutdown, usesMethodDispatch };