@tasker-systems/tasker 0.1.7 → 0.1.8

package/dist/{index-CRCYa9Xk.d.ts → index-CVhy3k3k.d.ts}

@@ -1244,9 +1244,25 @@ declare class StepExecutionSubscriber {
     /**
      * Send a completion result to Rust via FFI and handle the response.
      *
+     * If the primary FFI call fails (e.g. serialization error, unexpected
+     * type mismatch), we construct a guaranteed-safe failure result so the
+     * step is marked as permanently failed rather than silently lost.
+     *
      * @returns true if the completion was accepted by Rust, false otherwise
      */
     private sendCompletionViaFfi;
+    /**
+     * Submit a minimal safe-failure result after the primary FFI call fails.
+     *
+     * Builds a primitive-only result guaranteed to serialize, then attempts
+     * to submit it. Throws if the fallback is also rejected or fails,
+     * since the step would otherwise be silently lost.
+     */
+    private submitFallbackFailure;
+    /**
+     * Throw an error indicating a step has been orphaned (both primary and fallback failed).
+     */
+    private throwOrphanedError;
     /**
      * Handle successful FFI completion submission.
      */
@@ -1259,6 +1275,14 @@ declare class StepExecutionSubscriber {
      * Handle FFI completion error.
      */
     private handleFfiError;
+    /**
+     * Build a minimal NapiStepExecutionResult guaranteed to serialize through napi-rs.
+     *
+     * Uses only primitive values so there is zero chance of a secondary
+     * serialization failure. The step will be marked as permanently failed
+     * rather than silently lost.
+     */
+    private buildFfiSafeFailure;
 }
 
 /**

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { NapiModule, FfiLayer, FfiDomainEvent, FfiLayerConfig } from './ffi/index.js';
 export { BootstrapConfig as FfiBootstrapConfig, BootstrapResult as FfiBootstrapResult, FfiDispatchMetrics, LogFields as FfiLogFields, FfiStepEvent, StopResult as FfiStopResult, WorkerStatus as FfiWorkerStatus, NapiBackoffHint, NapiCheckpointYieldData, NapiClientResult, NapiDependencyResult, NapiDispatchMetrics, NapiDomainEvent, NapiDomainEventMetadata, NapiListTasksParams, NapiOrchestrationMetadata, NapiStepDefinition, NapiStepEvent, NapiStepExecutionError, NapiStepExecutionMetadata, NapiStepExecutionResult, NapiTaskInfo, NapiTaskRequest, NapiWorkflowStep, StepExecutionResult } from './ffi/index.js';
-import { S as StepHandlerResult, a as StepHandler, B as BatchWorkerConfig, b as StepContext, c as StepHandlerClass, E as ExecutableHandler, T as TaskerEventEmitter, d as EventPoller, e as StepExecutionSubscriber, f as EventSystem } from './index-CRCYa9Xk.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-CRCYa9Xk.js';
+import { S as StepHandlerResult, a as StepHandler, B as BatchWorkerConfig, b as StepContext, c as StepHandlerClass, E as ExecutableHandler, T as TaskerEventEmitter, d as EventPoller, e as StepExecutionSubscriber, f as EventSystem } from './index-CVhy3k3k.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-CVhy3k3k.js';
 import { Logger } from 'pino';
 import 'eventemitter3';
 
@@ -220,6 +220,155 @@ declare function getRustVersion(module?: NapiModule): string;
  */
 declare function healthCheck(module?: NapiModule): boolean;
 
+/**
+ * Client response types matching tasker-shared API response structs.
+ *
+ * These interfaces mirror the Rust types in `tasker_shared::types::api::orchestration`
+ * that are serialized to JSON via `serde_json::to_value()` in the FfiClientBridge.
+ * Field names use snake_case because serde's default serialization preserves the
+ * Rust field names.
+ *
+ * Source of truth: tasker-shared/src/types/api/orchestration.rs
+ */
+/**
+ * Step readiness analysis from the orchestration database function.
+ *
+ * Mirrors: tasker_shared::database::sql_functions::StepReadinessStatus
+ */
+interface StepReadinessStatus {
+    workflow_step_uuid: string;
+    task_uuid: string;
+    named_step_uuid: string;
+    name: string;
+    current_state: string;
+    dependencies_satisfied: boolean;
+    retry_eligible: boolean;
+    ready_for_execution: boolean;
+    last_failure_at: string | null;
+    next_retry_at: string | null;
+    total_parents: number;
+    completed_parents: number;
+    attempts: number;
+    max_attempts: number;
+    backoff_request_seconds: number | null;
+    last_attempted_at: string | null;
+}
+/**
+ * Task details response with execution context and step readiness.
+ *
+ * Mirrors: tasker_shared::types::api::orchestration::TaskResponse
+ */
+interface TaskResponse {
+    task_uuid: string;
+    name: string;
+    namespace: string;
+    version: string;
+    status: string;
+    created_at: string;
+    updated_at: string;
+    completed_at: string | null;
+    context: Record<string, unknown>;
+    initiator: string;
+    source_system: string;
+    reason: string;
+    priority: number | null;
+    tags: string[] | null;
+    correlation_id: string;
+    parent_correlation_id: string | null;
+    total_steps: number;
+    pending_steps: number;
+    in_progress_steps: number;
+    completed_steps: number;
+    failed_steps: number;
+    ready_steps: number;
+    execution_status: string;
+    recommended_action: string;
+    completion_percentage: number;
+    health_status: string;
+    steps: StepReadinessStatus[];
+}
+/**
+ * Pagination metadata for list responses.
+ *
+ * Mirrors: tasker_shared::models::core::task::PaginationInfo
+ */
+interface PaginationInfo {
+    total: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+}
+/**
+ * Task list response with pagination.
+ *
+ * Mirrors: tasker_shared::types::api::orchestration::TaskListResponse
+ */
+interface TaskListResponse {
+    tasks: TaskResponse[];
+    pagination: PaginationInfo;
+}
+/**
+ * Cancel task response.
+ *
+ * Constructed directly in FfiClientBridge::cancel_task as `{ "cancelled": true }`.
+ */
+interface CancelTaskResponse {
+    cancelled: boolean;
+}
+/**
+ * Step details response with readiness information.
+ *
+ * Mirrors: tasker_shared::types::api::orchestration::StepResponse
+ */
+interface StepResponse {
+    step_uuid: string;
+    task_uuid: string;
+    name: string;
+    created_at: string;
+    updated_at: string;
+    completed_at: string | null;
+    results: Record<string, unknown> | null;
+    current_state: string;
+    dependencies_satisfied: boolean;
+    retry_eligible: boolean;
+    ready_for_execution: boolean;
+    total_parents: number;
+    completed_parents: number;
+    attempts: number;
+    max_attempts: number;
+    last_failure_at: string | null;
+    next_retry_at: string | null;
+    last_attempted_at: string | null;
+}
+/**
+ * Step audit record for SOC2-compliant audit trails.
+ *
+ * Mirrors: tasker_shared::types::api::orchestration::StepAuditResponse
+ */
+interface StepAuditResponse {
+    audit_uuid: string;
+    workflow_step_uuid: string;
+    transition_uuid: string;
+    task_uuid: string;
+    recorded_at: string;
+    worker_uuid?: string;
+    correlation_id?: string;
+    success: boolean;
+    execution_time_ms?: number;
+    result?: Record<string, unknown>;
+    step_name: string;
+    from_state?: string;
+    to_state: string;
+}
+/**
+ * Health check response.
+ *
+ * Constructed directly in FfiClientBridge::health_check as `{ "healthy": true }`.
+ */
+interface HealthCheckResponse {
+    healthy: boolean;
+}
+
 /**
  * High-level client wrapper for orchestration API operations.
  *
@@ -229,14 +378,11 @@ declare function healthCheck(module?: NapiModule): boolean;
  *
  * @example
  * ```typescript
- * import { FfiLayer, TaskerClient } from '@tasker-systems/tasker';
- *
- * const ffiLayer = new FfiLayer();
- * await ffiLayer.load();
- * const client = new TaskerClient(ffiLayer);
+ * import { getTaskerClient } from '@tasker-systems/tasker';
  *
+ * const client = await getTaskerClient();
  * const task = client.createTask({ name: 'process_order', namespace: 'ecommerce' });
- * console.log(task.taskUuid);
+ * console.log(task.task_uuid);
  * ```
  *
  * @packageDocumentation
@@ -307,26 +453,26 @@ declare class TaskerClient {
      * Create a task via the orchestration API.
      *
      * @param options - Task creation options (only `name` is required)
-     * @returns Typed task response data
+     * @returns Task response with execution context and step readiness
      * @throws TaskerClientError if the operation fails
      */
-    createTask(options: CreateTaskOptions): unknown;
+    createTask(options: CreateTaskOptions): TaskResponse;
     /**
      * Get a task by UUID.
      *
      * @param taskUuid - The task UUID
-     * @returns Typed task response data
+     * @returns Task response with execution context and step readiness
      * @throws TaskerClientError if the operation fails
      */
-    getTask(taskUuid: string): unknown;
+    getTask(taskUuid: string): TaskResponse;
     /**
      * List tasks with optional filtering and pagination.
      *
      * @param options - Filtering and pagination options
-     * @returns Typed task list response data
+     * @returns Task list with pagination metadata
      * @throws TaskerClientError if the operation fails
      */
-    listTasks(options?: ListTasksOptions): unknown;
+    listTasks(options?: ListTasksOptions): TaskListResponse;
     /**
      * Cancel a task by UUID.
      *
@@ -338,37 +484,42 @@ declare class TaskerClient {
      * List workflow steps for a task.
      *
      * @param taskUuid - The task UUID
-     * @returns Array of step data
+     * @returns Array of step responses with readiness information
      * @throws TaskerClientError if the operation fails
      */
-    listTaskSteps(taskUuid: string): unknown;
+    listTaskSteps(taskUuid: string): StepResponse[];
     /**
      * Get a specific workflow step.
      *
      * @param taskUuid - The task UUID
      * @param stepUuid - The step UUID
-     * @returns Typed step response data
+     * @returns Step response with readiness information
      * @throws TaskerClientError if the operation fails
      */
-    getStep(taskUuid: string, stepUuid: string): unknown;
+    getStep(taskUuid: string, stepUuid: string): StepResponse;
     /**
      * Get audit history for a workflow step.
      *
      * @param taskUuid - The task UUID
      * @param stepUuid - The step UUID
-     * @returns Array of audit history entries
+     * @returns Array of audit history entries with attribution context
      * @throws TaskerClientError if the operation fails
      */
-    getStepAuditHistory(taskUuid: string, stepUuid: string): unknown;
+    getStepAuditHistory(taskUuid: string, stepUuid: string): StepAuditResponse[];
     /**
      * Check orchestration API health.
      *
-     * @returns Typed health response data
+     * @returns Health status from the orchestration API
      * @throws TaskerClientError if the operation fails
      */
-    healthCheck(): unknown;
+    healthCheck(): HealthCheckResponse;
     /**
      * Unwrap a NapiClientResult envelope, throwing on error.
+     *
+     * The type parameter allows callers to assert the expected response shape.
+     * The actual data comes from Rust via serde_json serialization, so the
+     * runtime shape is guaranteed by the Rust type system — the cast here
+     * is safe at the FFI boundary.
      */
     private unwrap;
     /**
@@ -376,6 +527,37 @@ declare class TaskerClient {
      */
     private getModule;
 }
+/**
+ * Returns a loaded FfiLayer singleton, initializing it on first call.
+ *
+ * The native library is loaded once and reused for all subsequent calls.
+ * Safe to call concurrently — concurrent callers await the same load promise.
+ *
+ * @example
+ * ```typescript
+ * import { getFfiLayer } from '@tasker-systems/tasker';
+ *
+ * const ffiLayer = await getFfiLayer();
+ * // Use for custom TaskerClient construction or direct FFI access
+ * ```
+ */
+declare function getFfiLayer(): Promise<FfiLayer>;
+/**
+ * Returns a TaskerClient backed by the shared FfiLayer singleton.
+ *
+ * This is the recommended entry point for most consumers. The FfiLayer
+ * is loaded lazily on first call and reused thereafter.
+ *
+ * @example
+ * ```typescript
+ * import { getTaskerClient } from '@tasker-systems/tasker';
+ *
+ * const client = await getTaskerClient();
+ * const task = client.createTask({ name: 'process_order', namespace: 'ecommerce' });
+ * console.log(task.task_uuid);
+ * ```
+ */
+declare function getTaskerClient(): Promise<TaskerClient>;
 
 /**
  * API mixin for HTTP functionality.
@@ -4361,4 +4543,4 @@ declare class WorkerServer {
     private cleanupOnError;
 }
 
-export { type APICapable, APIMixin, ApiHandler, type ApiHandlerArgs, type ApiHandlerOptions, ApiResponse, BasePublisher, type BaseResolver, BaseSubscriber, type BatchAggregationResult, type BatchAnalyzerOutcome, type BatchConfig, type BatchMetadata, type BatchProcessingOutcome, type BatchWorkerContext, type BatchWorkerOutcome, type Batchable, BatchableMixin, type BootstrapConfig, type BootstrapResult, ClassLookupResolver, type CreateBatchesOutcome, type CreateTaskOptions, type CursorConfig, Decision, 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, FfiDomainEvent, FfiLayer, FfiLayerConfig, type HandlerArgs, type HandlerDefinition, type HandlerEntry, type HandlerFactory, type HandlerFn, type HandlerOptions, HandlerRegistry, type HandlerSpec, HandlerSystem, InProcessDomainEventPoller, type ListTasksOptions, type LogFields, MethodDispatchError, MethodDispatchWrapper, NapiModule, type NoBatchesOutcome, NoResolverMatchError, PermanentError, type PollerStats, type PublishContext, PublisherNotFoundError, PublisherRegistry, PublisherValidationError, RegistryFrozenError, RegistryResolver, type RegistryResolverStatic, ResolutionError, ResolverChain, type ResolverConfig, ResolverNotFoundError, RetryableError, 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, WorkerServer, type WorkerServerConfig, type WorkerStatus, aggregateBatchResults, applyAPI, applyBatchable, applyDecision, bootstrapWorker, createBatchWorkerContext, createBatches, createDomainEvent, createFfiPollAdapter, createLogger, createStepEventContext, defineApiHandler, defineBatchAnalyzer, defineBatchWorker, defineDecisionHandler, defineHandler, 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, type ApiHandlerArgs, type ApiHandlerOptions, ApiResponse, BasePublisher, type BaseResolver, BaseSubscriber, type BatchAggregationResult, type BatchAnalyzerOutcome, type BatchConfig, type BatchMetadata, type BatchProcessingOutcome, type BatchWorkerContext, type BatchWorkerOutcome, type Batchable, BatchableMixin, type BootstrapConfig, type BootstrapResult, type CancelTaskResponse, ClassLookupResolver, type CreateBatchesOutcome, type CreateTaskOptions, type CursorConfig, Decision, 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, FfiDomainEvent, FfiLayer, FfiLayerConfig, type HandlerArgs, type HandlerDefinition, type HandlerEntry, type HandlerFactory, type HandlerFn, type HandlerOptions, HandlerRegistry, type HandlerSpec, HandlerSystem, type HealthCheckResponse, InProcessDomainEventPoller, type ListTasksOptions, type LogFields, MethodDispatchError, MethodDispatchWrapper, NapiModule, type NoBatchesOutcome, NoResolverMatchError, type PaginationInfo, PermanentError, type PollerStats, type PublishContext, PublisherNotFoundError, PublisherRegistry, PublisherValidationError, RegistryFrozenError, RegistryResolver, type RegistryResolverStatic, ResolutionError, ResolverChain, type ResolverConfig, ResolverNotFoundError, RetryableError, type RustBatchWorkerInputs, type RustCursorConfig, type ServerComponents, type HealthCheckResult as ServerHealthCheckResult, type ServerState, type ServerStatus, ShutdownController, type ShutdownHandler, type StepAuditResponse, StepContext, type StepEventContext, StepExecutionSubscriber, StepHandler, StepHandlerClass, StepHandlerResult, type StepReadinessStatus, type StepResponse, type StepResult, type StopResult, type SubscriberClass, SubscriberRegistry, type SubscriberStats, type TaskListResponse, type TaskResponse, TaskerClient, TaskerClientError, TaskerEventEmitter, WorkerServer, type WorkerServerConfig, type WorkerStatus, aggregateBatchResults, applyAPI, applyBatchable, applyDecision, bootstrapWorker, createBatchWorkerContext, createBatches, createDomainEvent, createFfiPollAdapter, createLogger, createStepEventContext, defineApiHandler, defineBatchAnalyzer, defineBatchWorker, defineDecisionHandler, defineHandler, effectiveMethod, ffiEventToDomainEvent, fromCallable, fromDto, getFfiLayer, getRustVersion, getTaskerClient, getVersion, getWorkerStatus, hasResolverHint, healthCheck, isCreateBatches, isNoBatches, isWorkerRunning, logDebug, logError, logInfo, logTrace, logWarn, noBatches, normalizeToDefinition, stopWorker, transitionToGracefulShutdown, usesMethodDispatch };