@tasker-systems/tasker 0.1.3 → 0.1.5

package/dist/ffi/index.d.ts

@@ -1,308 +1,389 @@
-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';
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/** Configuration for bootstrapping the worker. */
+interface BootstrapConfig {
+  namespace?: string
+  configPath?: string
+}
+
+/** Result of bootstrapping the worker. */
+interface BootstrapResult {
+  success: boolean
+  status: string
+  message: string
+  workerId?: string
+}
+
+/** Checkpoint yield data for batch processing (TAS-125). */
+interface NapiCheckpointYieldData {
+  stepUuid: string
+  cursor: any
+  itemsProcessed: number
+  accumulatedResults?: any
+}
 
 /**
- * Runtime detection for TypeScript/JavaScript workers.
+ * Client operation result.
  *
- * Detects whether the code is running in Bun, Node.js, Deno, or an unknown runtime.
- */
-/**
- * Supported JavaScript/TypeScript runtimes
+ * Maintains the existing TypeScript API surface with success/data/error envelope.
  */
-type RuntimeType = 'bun' | 'node' | 'deno' | 'unknown';
-/**
- * Runtime information including version details
- */
-interface RuntimeInfo {
-    type: RuntimeType;
-    version: string;
-    platform: string;
-    arch: string;
+interface NapiClientResult {
+  success: boolean
+  data?: any
+  error?: string
+  recoverable?: boolean
+}
+
+interface NapiDependencyResult {
+  stepUuid: string
+  success: boolean
+  result: any
+  status: string
+  errorMessage?: string
+  errorType?: string
+  errorRetryable?: boolean
+}
+
+/** FFI dispatch metrics. */
+interface NapiDispatchMetrics {
+  pendingCount: number
+  starvationDetected: boolean
+  starvingEventCount: number
+  oldestPendingAgeMs?: number
+  newestPendingAgeMs?: number
+  oldestEventId?: string
+}
+
+/** Domain event from in-process event bus (fast path). */
+interface NapiDomainEvent {
+  eventId: string
+  eventName: string
+  eventVersion: string
+  metadata: NapiDomainEventMetadata
+  payload: any
 }
+
+/** Metadata attached to domain events. */
+interface NapiDomainEventMetadata {
+  taskUuid: string
+  stepUuid?: string
+  stepName?: string
+  namespace: string
+  correlationId: string
+  firedAt: string
+  firedBy?: string
+}
+
+/** Parameters for listing tasks. */
+interface NapiListTasksParams {
+  limit?: number
+  offset?: number
+  namespace?: string
+  status?: string
+}
+
+interface NapiStepDefinition {
+  name: string
+  description?: string
+  handlerCallable: string
+  handlerMethod?: string
+  handlerResolver?: string
+  handlerInitialization: any
+  systemDependency?: string
+  dependencies: Array<string>
+  timeoutSeconds?: number
+  retryRetryable: boolean
+  retryMaxAttempts: number
+  retryBackoff: string
+  retryBackoffBaseMs?: number
+  retryMaxBackoffMs?: number
+}
+
+/** A step event dispatched to the TypeScript handler. */
+interface NapiStepEvent {
+  eventId: string
+  taskUuid: string
+  stepUuid: string
+  correlationId: string
+  traceId?: string
+  spanId?: string
+  taskCorrelationId: string
+  parentCorrelationId?: string
+  task: NapiTaskInfo
+  workflowStep: NapiWorkflowStep
+  stepDefinition: NapiStepDefinition
+  dependencyResults: Record<string, NapiDependencyResult>
+}
+
+interface NapiTaskInfo {
+  taskUuid: string
+  namedTaskUuid: string
+  name: string
+  namespace: string
+  version: string
+  context?: any
+  correlationId: string
+  parentCorrelationId?: string
+  complete: boolean
+  priority: number
+  initiator?: string
+  sourceSystem?: string
+  reason?: string
+  tags?: any
+  identityHash: string
+  createdAt: string
+  updatedAt: string
+  requestedAt: string
+}
+
 /**
- * Detect the current JavaScript/TypeScript runtime.
+ * Task creation request — crosses FFI as native JS object.
  *
- * @returns The detected runtime type
- */
-declare function detectRuntime(): RuntimeType;
-/**
- * Check if running in Bun
- */
-declare function isBun(): boolean;
-/**
- * Check if running in Node.js
+ * In koffi, this was serialized to JSON and parsed with
+ * `serde_json::Deserializer::from_str` to tolerate trailing bytes.
+ * In napi-rs, no serialization needed. No trailing bytes. No TAS-283.
  */
-declare function isNode(): boolean;
-/**
- * Check if running in Deno
- */
-declare function isDeno(): boolean;
+interface NapiTaskRequest {
+  name: string
+  namespace: string
+  version: string
+  /** Native JS object — napi-rs handles this via serde-json feature */
+  context: any
+  initiator: string
+  sourceSystem: string
+  reason: string
+  tags?: Array<string>
+  priority?: number
+  correlationId?: string
+  parentCorrelationId?: string
+  idempotencyKey?: string
+}
+
+interface NapiWorkflowStep {
+  workflowStepUuid: string
+  taskUuid: string
+  namedStepUuid: string
+  name: string
+  templateStepName: string
+  retryable: boolean
+  maxAttempts: number
+  attempts: number
+  inProcess: boolean
+  processed: boolean
+  inputs?: any
+  results?: any
+  backoffRequestSeconds?: number
+  processedAt?: string
+  lastAttemptedAt?: string
+  createdAt: string
+  updatedAt: string
+  checkpoint?: any
+}
+
+/** Worker status information. */
+interface WorkerStatus {
+  success: boolean
+  running: boolean
+  workerId?: string
+  status?: string
+  environment?: string
+}
+
 /**
- * Get detailed runtime information
+ * Step execution result sent back to Rust from TypeScript handlers.
+ *
+ * Mirrors: bridge.rs `NapiStepExecutionResult` with `#[napi(object)]`.
+ * Uses `| null` instead of `?:` because we explicitly construct these.
  */
-declare function getRuntimeInfo(): RuntimeInfo;
+interface NapiStepExecutionResult {
+    stepUuid: string;
+    success: boolean;
+    result: unknown;
+    status: 'completed' | 'failed' | 'error';
+    metadata: NapiStepExecutionMetadata;
+    error?: NapiStepExecutionError;
+    orchestrationMetadata?: NapiOrchestrationMetadata;
+}
+interface NapiStepExecutionMetadata {
+    executionTimeMs: number;
+    workerId?: string;
+    completedAt: string;
+    retryable?: boolean;
+    errorType?: string;
+    errorCode?: string;
+    custom?: Record<string, unknown>;
+}
+interface NapiStepExecutionError {
+    message: string;
+    errorType?: string;
+    retryable?: boolean;
+    statusCode?: number;
+    backtrace?: string[];
+    context?: Record<string, unknown>;
+}
 /**
- * Get the path to the native library.
+ * Orchestration metadata for workflow coordination hints.
  *
- * REQUIRES: TASKER_FFI_LIBRARY_PATH environment variable to be set,
- * OR an explicit basePath parameter must be provided.
+ * Handlers can return this to influence orchestration decisions — e.g.,
+ * passing Retry-After headers from external APIs, requesting explicit
+ * backoff, or providing domain-specific routing hints.
  *
- * This explicit requirement prevents confusion from automatic debug/release
- * library discovery and ensures intentional configuration at build/runtime.
+ * Matches: tasker_shared::messaging::message::OrchestrationMetadata
+ */
+interface NapiOrchestrationMetadata {
+    headers?: Record<string, string>;
+    errorContext?: string | null;
+    backoffHint?: NapiBackoffHint | null;
+    custom?: Record<string, unknown>;
+}
+/**
+ * Backoff hint from handler to orchestration system.
  *
- * @param basePath Optional explicit base path to the library directory
- * @returns Path to the native library
- * @throws Error if TASKER_FFI_LIBRARY_PATH is not set and no basePath provided
+ * Matches: tasker_shared::messaging::message::BackoffHint
  */
-declare function getLibraryPath(basePath?: string): string;
+interface NapiBackoffHint {
+    backoffType: string;
+    delaySeconds: number;
+    context?: string | null;
+}
+/** @deprecated Use NapiStepEvent directly */
+type FfiStepEvent = NapiStepEvent;
+/** @deprecated Use NapiDispatchMetrics directly */
+type FfiDispatchMetrics = NapiDispatchMetrics;
+/** @deprecated Use NapiDomainEvent directly */
+type FfiDomainEvent = NapiDomainEvent;
+/** @deprecated Use NapiDomainEventMetadata directly */
+type FfiDomainEventMetadata = NapiDomainEventMetadata;
+/** @deprecated Use NapiStepExecutionResult directly */
+type StepExecutionResult = NapiStepExecutionResult;
+/** Log fields for structured logging */
+interface LogFields {
+    [key: string]: string | number | boolean | null;
+}
+/** Checkpoint yield data alias */
+type CheckpointYieldData = NapiCheckpointYieldData;
+/** Stop result alias */
+type StopResult = WorkerStatus;
 
 /**
- * FfiLayer - Owns FFI runtime loading and lifecycle.
+ * FfiLayer - Owns napi-rs module loading and lifecycle.
  *
- * This class encapsulates the FFI runtime management:
- * - Runtime detection (Bun, Node.js, Deno)
- * - Library path discovery
- * - Runtime loading and unloading
+ * TAS-290: Simplified from the multi-runtime koffi approach.
+ * The napi-rs `.node` file IS the runtime — no runtime detection,
+ * no NodeRuntime/DenoRuntime adapters, no JSON serialization.
  *
  * Design principles:
  * - Explicit construction: No singleton pattern
- * - Clear ownership: Owns the runtime instance
+ * - Clear ownership: Owns the napi module instance
  * - Explicit lifecycle: load() and unload() methods
  */
 
+/**
+ * Interface for the napi-rs native module.
+ *
+ * These are the functions exported by the Rust `#[napi]` bindings.
+ * Function names are auto-camelCased by napi-rs from Rust snake_case.
+ */
+interface NapiModule {
+    getVersion(): string;
+    getRustVersion(): string;
+    healthCheck(): boolean;
+    bootstrapWorker(config: BootstrapConfig): BootstrapResult;
+    isWorkerRunning(): boolean;
+    getWorkerStatus(): WorkerStatus;
+    stopWorker(): WorkerStatus;
+    transitionToGracefulShutdown(): WorkerStatus;
+    pollStepEvents(): NapiStepEvent | null;
+    completeStepEvent(eventId: string, result: NapiStepExecutionResult): boolean;
+    pollInProcessEvents(): NapiDomainEvent | null;
+    checkpointYieldStepEvent(eventId: string, checkpoint: NapiCheckpointYieldData): boolean;
+    getFfiDispatchMetrics(): NapiDispatchMetrics;
+    checkStarvationWarnings(): void;
+    cleanupTimeouts(): void;
+    clientCreateTask(request: NapiTaskRequest): NapiClientResult;
+    clientGetTask(taskUuid: string): NapiClientResult;
+    clientListTasks(params: NapiListTasksParams): NapiClientResult;
+    clientCancelTask(taskUuid: string): NapiClientResult;
+    clientListTaskSteps(taskUuid: string): NapiClientResult;
+    clientGetStep(taskUuid: string, stepUuid: string): NapiClientResult;
+    clientGetStepAuditHistory(taskUuid: string, stepUuid: string): NapiClientResult;
+    clientHealthCheck(): NapiClientResult;
+    logError(message: string, fields?: Record<string, unknown>): void;
+    logWarn(message: string, fields?: Record<string, unknown>): void;
+    logInfo(message: string, fields?: Record<string, unknown>): void;
+    logDebug(message: string, fields?: Record<string, unknown>): void;
+    logTrace(message: string, fields?: Record<string, unknown>): void;
+}
 /**
  * Configuration for FfiLayer.
  */
 interface FfiLayerConfig {
-    /** Override runtime detection */
-    runtimeType?: RuntimeType;
-    /** Custom library path (overrides discovery) */
-    libraryPath?: string;
+    /** Custom module path (overrides discovery) */
+    modulePath?: string;
 }
 /**
- * Owns FFI runtime loading and lifecycle.
- *
- * Unlike RuntimeFactory, this class:
- * - Is NOT a singleton - created and passed explicitly
- * - Owns the runtime instance directly
- * - Has clear load/unload lifecycle
+ * Owns napi-rs module loading and lifecycle.
  *
  * @example
  * ```typescript
  * const ffiLayer = new FfiLayer();
  * await ffiLayer.load();
- * const runtime = ffiLayer.getRuntime();
- * // ... use runtime ...
+ * const module = ffiLayer.getModule();
+ * const result = module.bootstrapWorker({ namespace: 'default' });
  * await ffiLayer.unload();
  * ```
  */
 declare class FfiLayer {
-    private runtime;
-    private libraryPath;
-    private readonly runtimeType;
-    private readonly configuredLibraryPath;
-    /**
-     * Create a new FfiLayer.
-     *
-     * @param config - Optional configuration for runtime type and library path
-     */
+    private module;
+    private modulePath;
+    private readonly configuredModulePath;
     constructor(config?: FfiLayerConfig);
     /**
-     * Load the FFI library.
-     *
-     * Discovers and loads the native library for the current runtime.
+     * Load the napi-rs native module.
      *
-     * @param customPath - Optional override for library path (takes precedence over config)
-     * @throws Error if library not found or failed to load
+     * @param customPath - Optional override for module path
+     * @throws Error if module not found or failed to load
      */
     load(customPath?: string): Promise<void>;
     /**
-     * Unload the FFI library and release resources.
-     *
-     * Safe to call even if not loaded.
+     * Unload the native module and release resources.
      */
     unload(): Promise<void>;
     /**
-     * Check if the FFI library is loaded.
+     * Check if the native module is loaded.
      */
     isLoaded(): boolean;
     /**
-     * Get the loaded runtime.
+     * Get the loaded napi-rs module.
      *
-     * @throws Error if runtime is not loaded
-     */
-    getRuntime(): TaskerRuntime;
-    /**
-     * Get the path to the loaded library.
+     * @throws Error if module is not loaded
      */
-    getLibraryPath(): string | null;
+    getModule(): NapiModule;
     /**
-     * Get the detected runtime type.
-     */
-    getRuntimeType(): RuntimeType;
-    /**
-     * Find the FFI library path.
-     *
-     * Static method for finding the library path without creating an instance.
-     * Useful for test utilities and pre-flight checks.
-     *
-     * Resolution order:
-     * 1. TASKER_FFI_LIBRARY_PATH environment variable (explicit override)
-     * 2. Bundled native library in the package's native/ directory
+     * Backward-compatible alias for getModule().
      *
-     * @param _callerDir Deprecated parameter, kept for API compatibility
-     * @returns Path to the library if found and exists, null otherwise
+     * @deprecated Use getModule() instead
      */
-    static findLibraryPath(_callerDir?: string): string | null;
+    getRuntime(): NapiModule;
     /**
-     * Discover the FFI library path.
-     *
-     * Instance method that delegates to the static findLibraryPath.
+     * Get the path to the loaded module.
      */
-    private discoverLibraryPath;
+    getModulePath(): string | null;
     /**
-     * Create a runtime adapter for the configured runtime type.
+     * Find the napi-rs module path.
      *
-     * NOTE: We use koffi (NodeRuntime) for both Node.js and Bun because:
-     * - bun:ffi is experimental with known bugs (per Bun docs)
-     * - koffi is stable and works with both Node.js and Bun via Node-API
-     * - See: https://bun.sh/docs/runtime/node-api
+     * Resolution order:
+     * 1. TASKER_FFI_MODULE_PATH environment variable (explicit override, for unusual setups)
+     * 2. Bundled .node file in package directory (standard path — `napi build --platform` places it here)
      */
-    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;
+    static findModulePath(): string | null;
     /**
-     * Read a C string from a pointer and free the Rust-allocated memory.
+     * Backward-compatible alias for findModulePath().
      *
-     * Uses koffi.decode with 'char' type and -1 length for null-terminated strings.
+     * @deprecated Use findModulePath() instead
      */
-    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;
+    static findLibraryPath(_callerDir?: string): string | null;
+    private discoverModulePath;
 }
 
-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 };
+export { type BootstrapConfig, type BootstrapResult, type CheckpointYieldData, type FfiDispatchMetrics, type FfiDomainEvent, type FfiDomainEventMetadata, FfiLayer, type FfiLayerConfig, type FfiStepEvent, type LogFields, type NapiBackoffHint, type NapiCheckpointYieldData, type NapiClientResult, type NapiDependencyResult, type NapiDispatchMetrics, type NapiDomainEvent, type NapiDomainEventMetadata, type NapiListTasksParams, type NapiModule, type NapiOrchestrationMetadata, type NapiStepDefinition, type NapiStepEvent, type NapiStepExecutionError, type NapiStepExecutionMetadata, type NapiStepExecutionResult, type NapiTaskInfo, type NapiTaskRequest, type NapiWorkflowStep, type StepExecutionResult, type StopResult, type WorkerStatus };