@gravito/ripple 4.0.1 → 4.0.3

package/dist/core/src/events/EventPriorityQueue.d.ts

@@ -1,14 +1,13 @@
 import type { Span } from '@opentelemetry/api';
 import type { ActionCallback } from '../HookManager';
-import { BackpressureManager } from './BackpressureManager';
-import { CircuitBreaker } from './CircuitBreaker';
+import type { BackpressureManager } from './BackpressureManager';
 import type { DeadLetterQueue } from './DeadLetterQueue';
 import type { EventBackend } from './EventBackend';
 import type { EventOptions } from './EventOptions';
 import type { EventMetrics } from './observability/EventMetrics';
 import type { EventTracing } from './observability/EventTracing';
 import type { OTelEventMetrics } from './observability/OTelEventMetrics';
-import { type PriorityStatistics } from './PriorityEscalationManager';
+import type { PriorityStatistics } from './PriorityEscalationManager';
 import type { RetryScheduler } from './RetryScheduler';
 import type { BackpressureStrategy, EventQueueConfig, EventTask, MultiPriorityQueueDepth } from './types';
 import type { WorkerPool } from './WorkerPool';
@@ -23,279 +22,42 @@ export type { EventTask, EventQueueConfig, BackpressureStrategy };
  *
  * Supports automatic priority escalation based on wait time.
  *
+ * Composed of:
+ * - {@link QueueCore}: queue data structures and backpressure logic
+ * - {@link TaskExecutor}: task execution, retry, circuit breaker, DLQ
+ *
  * @internal
  */
 export declare class EventPriorityQueue implements EventBackend {
-    private criticalPriority;
-    private highPriority;
-    private normalPriority;
-    private lowPriority;
+    private queueCore;
+    private taskExecutor;
     private processing;
-    private taskIdCounter;
-    private dlq?;
-    private persistentDLQHandler?;
-    private config;
-    private processingPartitions;
-    private eventCircuitBreakers;
-    private eventMetrics?;
-    private otelEventMetrics?;
-    private eventTracing?;
-    private currentDispatchSpan?;
-    private backpressureManager?;
     private workerPool?;
-    private retryScheduler?;
-    private priorityStats?;
     constructor(config?: EventQueueConfig);
-    /**
-     * Set the Dead Letter Queue for failed events.
-     *
-     * @param dlq - Dead Letter Queue instance
-     */
     setDeadLetterQueue(dlq: DeadLetterQueue): void;
-    /**
-     * Set the persistent DLQ handler for failed events.
-     *
-     * @param handler - Async handler function for persistent DLQ
-     */
     setPersistentDLQHandler(handler: (hook: string, args: unknown, options: EventOptions, error: Error, retryCount: number, firstFailedAt: number) => Promise<void>): void;
-    /**
-     * Set the EventMetrics instance for recording circuit breaker metrics.
-     *
-     * @param metrics - EventMetrics instance
-     * @internal
-     */
     setEventMetrics(metrics: EventMetrics): void;
-    /**
-     * Set the OTelEventMetrics instance for recording DLQ and backpressure metrics.
-     *
-     * @param metrics - OTelEventMetrics instance
-     * @internal
-     */
     setOTelEventMetrics(metrics: OTelEventMetrics): void;
-    /**
-     * Set the PriorityStatistics instance for tracking priority distribution.
-     *
-     * @param stats - PriorityStatistics instance
-     * @internal
-     */
     setPriorityStatistics(stats: PriorityStatistics): void;
-    /**
-     * Get the PriorityStatistics instance.
-     *
-     * @returns PriorityStatistics instance or undefined
-     * @internal
-     */
     getPriorityStatistics(): PriorityStatistics | undefined;
-    /**
-     * Set the EventTracing instance for distributed tracing.
-     *
-     * @param tracing - EventTracing instance
-     * @internal
-     */
     setEventTracing(tracing: EventTracing): void;
-    /**
-     * Set the current dispatch span for creating child spans.
-     *
-     * @param span - Parent dispatch span
-     * @internal
-     */
     setCurrentDispatchSpan(span: Span | undefined): void;
-    /**
-     * Get the current dispatch span.
-     *
-     * @returns Current dispatch span or undefined
-     * @internal
-     */
     getCurrentDispatchSpan(): Span | undefined;
-    /**
-     * Set the RetryScheduler for async distributed retries.
-     *
-     * @param scheduler - RetryScheduler instance
-     * @internal
-     */
     setRetryScheduler(scheduler: RetryScheduler): void;
-    /**
-     * Get the RetryScheduler instance.
-     *
-     * @returns RetryScheduler instance or undefined
-     * @internal
-     */
     getRetryScheduler(): RetryScheduler | undefined;
-    /**
-     * Get or create a circuit breaker for an event hook.
-     *
-     * @param hook - Event hook name
-     * @param config - Circuit breaker configuration
-     * @returns Circuit breaker instance or undefined if not configured
-     * @internal
-     */
-    private getOrCreateEventCircuitBreaker;
-    /**
-     * Enqueue an event task for processing.
-     *
-     * @param hook - Event hook name
-     * @param args - Event arguments
-     * @param callbacks - Callbacks to execute
-     * @param options - Event options
-     * @returns Task ID
-     */
+    getCircuitBreaker(hook: string): import("@gravito/core").CircuitBreaker | undefined;
+    getCircuitBreakers(): Map<string, import("@gravito/core").CircuitBreaker>;
+    resetCircuitBreaker(hook: string): boolean;
+    setWorkerPool(pool: WorkerPool): void;
+    getWorkerPool(): WorkerPool | undefined;
+    getBackpressureManager(): BackpressureManager | undefined;
     enqueue(task: EventTask): string;
     enqueue(hook: string, args: unknown, callbacks: ActionCallback[], options: EventOptions): string;
-    /**
-     * Handle backpressure when queue is full.
-     * @returns True if space was made, false if event should be dropped
-     */
-    private handleBackpressure;
-    /**
-     * Drop the oldest event from the queue, prioritizing low priority events.
-     * Drops in order: LOW → NORMAL → HIGH → CRITICAL
-     */
-    private dropOldest;
-    /**
-     * Process the next task in the queue.
-     * Tasks are processed in priority order: high > normal > low
-     * If WorkerPool is configured, tasks are submitted to the pool for concurrent execution.
-     *
-     * @internal
-     */
-    private processNext;
-    /**
-     * Dequeue the next task based on priority and partition ordering.
-     * Priority order: CRITICAL > HIGH > NORMAL > LOW
-     *
-     * @returns Next task to process, or undefined if queue is empty
-     * @internal
-     */
-    private dequeue;
-    /**
-     * Dequeue a task from a priority queue, respecting partition ordering.
-     *
-     * @param queue - Priority queue to dequeue from
-     * @returns Next task to process, or undefined if all tasks are blocked by partition locks
-     * @internal
-     */
-    private dequeueFromPriority;
-    /**
-     * Execute an event task by running all its callbacks.
-     * Implements circuit breaker protection, retry logic with exponential backoff, and DLQ integration.
-     * Also handles partition ordering by acquiring and releasing partition locks.
-     *
-     * @param task - Event task to execute
-     * @internal
-     */
-    private executeTask;
-    /**
-     * Calculate retry delay based on backoff strategy.
-     *
-     * @param retryCount - Current retry attempt number
-     * @param backoff - Backoff strategy
-     * @param initialDelay - Initial delay in ms
-     * @param maxDelay - Maximum delay in ms
-     * @returns Delay in milliseconds
-     * @internal
-     */
-    private calculateRetryDelay;
-    /**
-     * Re-enqueue a task for retry.
-     *
-     * @param task - Task to retry
-     * @internal
-     */
-    private enqueueRetry;
-    /**
-     * Execute a callback with timeout.
-     *
-     * @param callback - Callback to execute
-     * @param args - Arguments to pass to callback
-     * @param timeoutMs - Timeout in milliseconds
-     * @internal
-     */
-    private executeWithTimeout;
-    /**
-     * Get the current depth of the queue.
-     *
-     * @returns Total number of tasks in the queue
-     */
+    enqueueBatch(tasks: EventTask[]): string[];
     getDepth(): number;
-    /**
-     * Get the depth of a specific priority queue.
-     *
-     * @param priority - Priority level
-     * @returns Number of tasks in the specified priority queue
-     */
     getDepthByPriority(priority: 'critical' | 'high' | 'normal' | 'low'): number;
-    /**
-     * Get the BackpressureManager instance if enabled.
-     *
-     * @returns BackpressureManager instance or undefined if not enabled
-     * @internal
-     */
-    getBackpressureManager(): BackpressureManager | undefined;
-    /**
-     * Set the WorkerPool for concurrent task execution.
-     *
-     * @param pool - WorkerPool instance
-     * @internal
-     */
-    setWorkerPool(pool: WorkerPool): void;
-    /**
-     * Get the WorkerPool instance if set.
-     *
-     * @returns WorkerPool instance or undefined if not set
-     * @internal
-     */
-    getWorkerPool(): WorkerPool | undefined;
-    /**
-     * Clear all tasks from the queue.
-     */
-    clear(): void;
-    /**
-     * Get circuit breaker for an event hook.
-     *
-     * @param hook - Event hook name
-     * @returns Circuit breaker instance or undefined
-     * @internal
-     */
-    getCircuitBreaker(hook: string): CircuitBreaker | undefined;
-    /**
-     * Get all circuit breakers.
-     *
-     * @returns Map of circuit breakers keyed by hook name
-     * @internal
-     */
-    getCircuitBreakers(): Map<string, CircuitBreaker>;
-    /**
-     * Reset a circuit breaker for an event hook.
-     *
-     * @param hook - Event hook name
-     * @returns True if reset, false if circuit breaker not found
-     * @internal
-     */
-    resetCircuitBreaker(hook: string): boolean;
-    /**
-     * Batch enqueue multiple tasks (FS-102).
-     * Supports aggregation layer batch submission.
-     *
-     * @param tasks - Array of tasks to enqueue
-     * @returns Array of task IDs
-     * @internal
-     */
-    enqueueBatch(tasks: EventTask[]): string[];
-    /**
-     * Get queue depth for each priority level (FS-103).
-     * Used by BackpressureManager for multi-priority depth monitoring.
-     *
-     * @returns Queue depth snapshot with depths for each priority
-     * @internal
-     */
     getQueueDepthByPriority(): MultiPriorityQueueDepth;
-    /**
-     * Sync queue depth to BackpressureManager (FS-103).
-     * Called whenever queue depth changes to keep BackpressureManager
-     * synchronized with real-time queue state.
-     *
-     * @private
-     * @internal
-     */
-    private syncBackpressure;
+    clear(): void;
+    dequeue(): EventTask | undefined;
+    private processNext;
 }

package/dist/core/src/events/index.d.ts

@@ -2,24 +2,25 @@
  * Event system exports for async event dispatch.
  * @packageDocumentation
  */
+export * from './EventBackend';
+export type { EventOptions } from './EventOptions';
+export { DEFAULT_EVENT_OPTIONS } from './EventOptions';
+export type { BackpressureStrategy, EventQueueConfig, EventTask } from './types';
 export type { BackpressureConfig, BackpressureDecision, BackpressureMetricsSnapshot, } from './BackpressureManager';
 export { BackpressureManager, BackpressureState } from './BackpressureManager';
-export type { CircuitBreakerOptions } from './CircuitBreaker';
+export type { CircuitBreakerMetrics, CircuitBreakerMetricsRecorder, CircuitBreakerOptions, } from './CircuitBreaker';
 export { CircuitBreaker, CircuitBreakerState } from './CircuitBreaker';
-export type { DLQEntry, DLQFilter } from './DeadLetterQueue';
+export type { DLQEntry, DLQEntryCallback, DLQEntrySource, DLQFilter } from './DeadLetterQueue';
 export { DeadLetterQueue } from './DeadLetterQueue';
-export * from './EventBackend';
-export type { EventOptions } from './EventOptions';
-export { DEFAULT_EVENT_OPTIONS } from './EventOptions';
 export { EventPriorityQueue } from './EventPriorityQueue';
-export type { FlowControlContext, FlowControlStrategy } from './FlowControlStrategy';
-export { CompositeStrategy, createDefaultStrategies, PriorityRebalanceStrategy, QueueDepthStrategy, RateLimitStrategy, StarvationProtectionStrategy, } from './FlowControlStrategy';
-export type { EventStatus, MessageQueueBridgeConfig } from './MessageQueueBridge';
+export * from './FlowControlStrategy';
+export { IdempotencyCache } from './IdempotencyCache';
 export { MessageQueueBridge } from './MessageQueueBridge';
-export * from './observability';
-export type { QueueStats, RetrySchedulerConfig } from './RetryScheduler';
+export type { PriorityStatistics } from './PriorityEscalationManager';
+export { PriorityEscalationManager } from './PriorityEscalationManager';
+export type { RetrySchedulerConfig } from './RetryScheduler';
 export { RetryScheduler } from './RetryScheduler';
-export type { BackpressureStrategy, EventQueueConfig, EventTask } from './types';
+export type { DeadLetterDecision, MultiPriorityQueueDepth, WindowAdjustment } from './types';
 export { WorkerPool } from './WorkerPool';
 export type { WorkerPoolConfig, WorkerPoolStats, WorkerStats } from './WorkerPoolConfig';
 export { WorkerPoolMetrics } from './WorkerPoolMetrics';

package/dist/core/src/events/queue-core.d.ts

@@ -0,0 +1,77 @@
+import { BackpressureManager } from './BackpressureManager';
+import type { DeadLetterQueue } from './DeadLetterQueue';
+import type { OTelEventMetrics } from './observability/OTelEventMetrics';
+import { type PriorityStatistics } from './PriorityEscalationManager';
+import type { BackpressureStrategy, EventQueueConfig, EventTask, MultiPriorityQueueDepth } from './types';
+/**
+ * Result of an enqueue operation.
+ *
+ * - `{ status: 'queued', id }` - Task successfully queued
+ * - `{ status: 'dropped' }` - Task dropped due to backpressure
+ * - `{ status: 'delayed', id, delayMs }` - Task should be re-enqueued after delayMs
+ *
+ * @internal
+ */
+export type EnqueueResult = {
+    status: 'queued';
+    id: string;
+} | {
+    status: 'dropped';
+} | {
+    status: 'delayed';
+    id: string;
+    delayMs: number;
+};
+/**
+ * Priority queue core: manages event task queues and backpressure.
+ *
+ * Handles enqueueing, dequeuing, backpressure logic, and priority escalation.
+ * This class is used internally by EventPriorityQueue as a composition target.
+ *
+ * @internal
+ */
+export declare class QueueCore {
+    criticalPriority: EventTask[];
+    highPriority: EventTask[];
+    normalPriority: EventTask[];
+    lowPriority: EventTask[];
+    processingPartitions: Set<string>;
+    private taskIdCounter;
+    private dlq?;
+    private otelEventMetrics?;
+    private backpressureManager?;
+    private priorityStats?;
+    private config;
+    constructor(config?: EventQueueConfig);
+    setDeadLetterQueue(dlq: DeadLetterQueue): void;
+    setOTelEventMetrics(metrics: OTelEventMetrics): void;
+    setPriorityStatistics(stats: PriorityStatistics): void;
+    getPriorityStatistics(): PriorityStatistics | undefined;
+    getBackpressureManager(): BackpressureManager | undefined;
+    getConfig(): EventQueueConfig;
+    getDLQ(): DeadLetterQueue | undefined;
+    createTaskId(): string;
+    /**
+     * Enqueue a task into the appropriate priority queue.
+     * Applies priority escalation and backpressure logic.
+     */
+    enqueue(task: EventTask): EnqueueResult;
+    /**
+     * Dequeue the next task based on priority and partition ordering.
+     * Priority order: CRITICAL > HIGH > NORMAL > LOW
+     */
+    dequeue(): EventTask | undefined;
+    /**
+     * Re-enqueue a task for retry.
+     */
+    enqueueRetry(task: EventTask): void;
+    getDepth(): number;
+    getDepthByPriority(priority: 'critical' | 'high' | 'normal' | 'low'): number;
+    getQueueDepthByPriority(): MultiPriorityQueueDepth;
+    clear(): void;
+    syncBackpressure(): void;
+    private handleBackpressure;
+    private dropOldest;
+    private dequeueFromPriority;
+}
+export type { BackpressureStrategy, EventQueueConfig, EventTask };

package/dist/core/src/events/task-executor.d.ts

@@ -0,0 +1,51 @@
+import type { Span } from '@opentelemetry/api';
+import { CircuitBreaker } from './CircuitBreaker';
+import type { DeadLetterQueue } from './DeadLetterQueue';
+import type { EventOptions } from './EventOptions';
+import type { EventMetrics } from './observability/EventMetrics';
+import type { EventTracing } from './observability/EventTracing';
+import type { OTelEventMetrics } from './observability/OTelEventMetrics';
+import type { RetryScheduler } from './RetryScheduler';
+import type { EventTask } from './types';
+/**
+ * Executes event tasks with circuit breaker protection, retry logic,
+ * exponential backoff, DLQ integration, and distributed tracing.
+ *
+ * @internal
+ */
+export declare class TaskExecutor {
+    private eventCircuitBreakers;
+    private eventMetrics?;
+    private otelEventMetrics?;
+    private eventTracing?;
+    private currentDispatchSpan?;
+    private retryScheduler?;
+    private dlq?;
+    private persistentDLQHandler?;
+    private enqueueRetryFn?;
+    setDeadLetterQueue(dlq: DeadLetterQueue): void;
+    setPersistentDLQHandler(handler: (hook: string, args: unknown, options: EventOptions, error: Error, retryCount: number, firstFailedAt: number) => Promise<void>): void;
+    setEventMetrics(metrics: EventMetrics): void;
+    setOTelEventMetrics(metrics: OTelEventMetrics): void;
+    setEventTracing(tracing: EventTracing): void;
+    setCurrentDispatchSpan(span: Span | undefined): void;
+    getCurrentDispatchSpan(): Span | undefined;
+    setRetryScheduler(scheduler: RetryScheduler): void;
+    getRetryScheduler(): RetryScheduler | undefined;
+    /**
+     * Set the callback to use when re-enqueueing a task after a retry delay.
+     */
+    setEnqueueRetryFn(fn: (task: EventTask) => void): void;
+    getCircuitBreaker(hook: string): CircuitBreaker | undefined;
+    getCircuitBreakers(): Map<string, CircuitBreaker>;
+    resetCircuitBreaker(hook: string): boolean;
+    /**
+     * Execute an event task by running all its callbacks.
+     * Implements circuit breaker protection, retry logic, and DLQ integration.
+     */
+    executeTask(task: EventTask, processingPartitions: Set<string>): Promise<void>;
+    private sendToDLQ;
+    private getOrCreateEventCircuitBreaker;
+    private calculateRetryDelay;
+    private executeWithTimeout;
+}

package/dist/core/src/ffi/NativeAccelerator.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 原生加速器統一入口
+ * 遵循 Galaxy Architecture 的運行時自適應模式
+ * 與 RuntimeAdapter 模式保持一致
+ *
+ * 📍 FFI 暫時禁用
+ * Bun 的構建系統在生成 ffi/index.js 時會產生 CJS compatibility helpers，
+ * 這些 helpers 與 ESM export 語句導致模組解析失敗。
+ * 即使使用 ESM import 也無法避免此問題（Bun 內部機制）。
+ *
+ * 解決方案：禁用 FFI，使用 JavaScript fallback（性能影響極小）
+ * TODO: 當 Bun 改進其 ESM 模組構建時重新啟用
+ */
+import type { CborAccelerator, NativeAcceleratorStatus } from './types';
+/**
+ * 原生加速器類別
+ * 提供運行時自適應的 CBOR 編碼/解碼加速
+ * - 在 Bun 環境下優先使用 C 編譯器實現（bun:ffi）
+ * - 在非 Bun 環境或 FFI 不可用時自動降級到 JavaScript 實現
+ */
+export declare class NativeAccelerator {
+    private static readonly DEBUG_ENV;
+    /**
+     * FFI 可用性緩存
+     * null: 未檢測, true: 可用, false: 不可用
+     */
+    private static available;
+    /**
+     * 當前加速器實例緩存
+     */
+    private static cborAccelerator;
+    /**
+     * 當前狀態
+     */
+    private static status;
+    /**
+     * 檢測原生 FFI 是否可用
+     * ⚠️ 當前全部返回 false（FFI 已禁用）
+     */
+    static isAvailable(): boolean;
+    /**
+     * 取得 CBOR 加速器實例
+     * 優先使用 Native，失敗則降級到 Fallback
+     */
+    static getCborAccelerator(): CborAccelerator;
+    /**
+     * 取得加速器狀態
+     */
+    static getStatus(): NativeAcceleratorStatus;
+    /**
+     * 重置加速器狀態（用於測試）
+     */
+    static reset(): void;
+    /**
+     * 檢查是否啟用調試模式
+     */
+    private static isDebugEnabled;
+    /**
+     * 更新狀態
+     */
+    private static updateStatus;
+}

package/dist/core/src/ffi/NativeHasher.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 原生雜湊加速器
+ * 運行時自適應實現，遵循 Galaxy Architecture 的設計模式
+ *
+ * 架構：
+ * - 在 Bun 環境：使用 Bun.CryptoHasher（C 實現，高效）
+ * - 其他環境：自動降級到 node:crypto
+ * - 完全相同的 API 和結果保證
+ *
+ * 性能：
+ * - Bun 環境：2-3x 快於 node:crypto（消除 N-API 開銷）
+ * - 跨運行時：完全相容性
+ *
+ * 應用場景：
+ * - FileStore.hashKey() 熱路徑
+ * - Encrypter.hash() 加密雜湊
+ * - 任何需要高效雜湊計算的地方
+ */
+import type { NativeHasherStatus } from './types';
+/**
+ * 原生雜湊加速器統一入口
+ * 提供運行時自適應的 SHA-256/HMAC-SHA256 計算
+ *
+ * 使用範例：
+ * ```typescript
+ * // SHA-256
+ * const hash = NativeHasher.sha256('data')
+ *
+ * // HMAC-SHA256
+ * const hmac = NativeHasher.hmacSha256('secret', 'message')
+ *
+ * // 檢查狀態
+ * const status = NativeHasher.getStatus()
+ * console.log(`使用: ${status.runtime}`)
+ * ```
+ */
+export declare class NativeHasher {
+    /**
+     * 當前加速器實例緩存
+     */
+    private static accelerator;
+    /**
+     * 當前狀態緩存
+     */
+    private static status;
+    /**
+     * 取得雜湊加速器實例
+     * 優先使用 Bun.CryptoHasher，失敗則降級到 node:crypto
+     *
+     * @returns 雜湊加速器實例
+     */
+    private static getAccelerator;
+    /**
+     * 檢測 Bun 運行時和 CryptoHasher 可用性
+     *
+     * @returns Bun.CryptoHasher 是否可用
+     */
+    private static isBunAvailable;
+    /**
+     * 更新狀態
+     *
+     * @param runtime - 當前使用的運行時
+     */
+    private static updateStatus;
+    /**
+     * 計算 SHA-256 雜湊
+     * 支援字串和二進制輸入
+     *
+     * @param input - 要雜湊的數據（字串或 Uint8Array）
+     * @returns 十六進制編碼的 SHA-256 雜湊值（64 字元）
+     *
+     * @example
+     * ```typescript
+     * const hash = NativeHasher.sha256('hello')
+     * // '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'
+     *
+     * // 支援 Uint8Array
+     * const bytes = new TextEncoder().encode('hello')
+     * const hash2 = NativeHasher.sha256(bytes)
+     * // 相同結果
+     * ```
+     */
+    static sha256(input: string | Uint8Array): string;
+    /**
+     * 計算 HMAC-SHA256
+     * 用於認證消息完整性
+     *
+     * @param key - HMAC 密鑰
+     * @param data - 要雜湊的數據
+     * @returns 十六進制編碼的 HMAC-SHA256 值（64 字元）
+     *
+     * @example
+     * ```typescript
+     * const hmac = NativeHasher.hmacSha256('secret', 'message')
+     * // '8b1a9953c4611296aed9e132b8502cf413b1b881fed3e8d26ab'...
+     *
+     * // 適用於加密驗證
+     * const iv = Buffer.from('...').toString('base64')
+     * const encrypted = '...'
+     * const mac = NativeHasher.hmacSha256(key, iv + encrypted)
+     * ```
+     */
+    static hmacSha256(key: string, data: string): string;
+    /**
+     * 取得加速器狀態
+     * 用於診斷和性能監測
+     *
+     * @returns 加速器狀態報告
+     *
+     * @example
+     * ```typescript
+     * const status = NativeHasher.getStatus()
+     * console.log(`可用: ${status.available}`)
+     * console.log(`運行時: ${status.runtime}`)
+     *
+     * // 條件邏輯
+     * if (status.runtime === 'bun-crypto-hasher') {
+     *   console.log('使用 Bun 原生實現（高效）')
+     * } else {
+     *   console.log('使用 node:crypto（相容性回退）')
+     * }
+     * ```
+     */
+    static getStatus(): NativeHasherStatus;
+    /**
+     * 重置加速器狀態
+     * 主要用於測試目的，允許重新初始化運行時檢測
+     *
+     * @internal
+     * @example
+     * ```typescript
+     * // 測試中
+     * NativeHasher.reset()
+     * // 下一次呼叫會重新偵測運行時
+     * const status = NativeHasher.getStatus()
+     * ```
+     */
+    static reset(): void;
+}