@tracehound/core 1.2.0

package/dist/core/notification-emitter.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Universal Notification API - Event emission for all consumers.
+ *
+ * RFC-0000 COMPLIANCE:
+ * - Read-only event emission (no backpressure)
+ * - Fire-and-forget semantics
+ * - No blocking on consumer processing
+ */
+/**
+ * All possible event types emitted by Tracehound.
+ */
+export type EventType = 'threat.detected' | 'evidence.quarantined' | 'evidence.evicted' | 'rate_limit.exceeded' | 'system.panic' | 'license.validated' | 'license.expired';
+/**
+ * Base event structure.
+ */
+export interface TracehoundEvent<T = unknown> {
+    /** Event type */
+    type: EventType;
+    /** Unix timestamp (ms) */
+    timestamp: number;
+    /** Event payload */
+    payload: T;
+    /** Unique event ID */
+    id: string;
+}
+export interface ThreatDetectedPayload {
+    scentId: string;
+    category: string;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    source: string;
+}
+export interface EvidenceQuarantinedPayload {
+    signature: string;
+    severity: 'low' | 'medium' | 'high' | 'critical';
+    sizeBytes: number;
+}
+export interface EvidenceEvictedPayload {
+    signature: string;
+    reason: 'capacity' | 'policy' | 'manual';
+}
+export interface RateLimitExceededPayload {
+    source: string;
+    retryAfterMs: number;
+}
+export interface SystemPanicPayload {
+    level: 'warning' | 'critical' | 'fatal';
+    reason: string;
+    context?: Record<string, unknown>;
+}
+export interface LicenseValidatedPayload {
+    tier: 'starter' | 'pro' | 'enterprise';
+    daysRemaining?: number;
+}
+export interface LicenseExpiredPayload {
+    tier: 'starter' | 'pro' | 'enterprise';
+    gracePeriod: boolean;
+}
+export interface WebhookConfig {
+    /** Webhook URL */
+    url: string;
+    /** Events to subscribe to (empty = all) */
+    events?: EventType[];
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Secret for HMAC signature */
+    secret?: string;
+    /** Retry configuration */
+    retry?: {
+        maxAttempts: number;
+        delayMs: number;
+    };
+}
+export type EventCallback<T = unknown> = (event: TracehoundEvent<T>) => void;
+/**
+ * Notification Emitter interface.
+ */
+export interface INotificationEmitter {
+    /**
+     * Register a callback for an event type.
+     */
+    on<T = unknown>(event: EventType, callback: EventCallback<T>): void;
+    /**
+     * Unregister a callback for an event type.
+     */
+    off<T = unknown>(event: EventType, callback: EventCallback<T>): void;
+    /**
+     * Subscribe to events as an async iterable.
+     * @param events - Event types to subscribe to (empty = all)
+     */
+    subscribe(events?: EventType[]): AsyncIterable<TracehoundEvent>;
+    /**
+     * Register a webhook for event delivery.
+     * @returns Webhook ID
+     */
+    registerWebhook(config: WebhookConfig): string;
+    /**
+     * Unregister a webhook.
+     */
+    unregisterWebhook(id: string): void;
+    /**
+     * Emit an event to all consumers.
+     */
+    emit<T>(type: EventType, payload: T): void;
+    /**
+     * Get emitter statistics.
+     */
+    readonly stats: NotificationEmitterStats;
+}
+export interface NotificationEmitterStats {
+    totalEmitted: number;
+    byType: Record<EventType, number>;
+    activeCallbacks: number;
+    activeSubscribers: number;
+    activeWebhooks: number;
+}
+/**
+ * Notification Emitter implementation.
+ */
+export declare class NotificationEmitter implements INotificationEmitter {
+    private callbacks;
+    private subscribers;
+    private webhooks;
+    private _totalEmitted;
+    private _byType;
+    private eventCounter;
+    on<T = unknown>(event: EventType, callback: EventCallback<T>): void;
+    off<T = unknown>(event: EventType, callback: EventCallback<T>): void;
+    subscribe(events?: EventType[]): AsyncIterable<TracehoundEvent>;
+    registerWebhook(config: WebhookConfig): string;
+    unregisterWebhook(id: string): void;
+    emit<T>(type: EventType, payload: T): void;
+    get stats(): NotificationEmitterStats;
+    private dispatchWebhook;
+    private sleep;
+}
+/**
+ * Create a Notification Emitter instance.
+ */
+export declare function createNotificationEmitter(): INotificationEmitter;
+//# sourceMappingURL=notification-emitter.d.ts.map

package/dist/core/notification-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-emitter.d.ts","sourceRoot":"","sources":["../../src/core/notification-emitter.ts"],"names":[],"mappings":"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"}

package/dist/core/notification-emitter.js

@@ -0,0 +1,197 @@
+/**
+ * Universal Notification API - Event emission for all consumers.
+ *
+ * RFC-0000 COMPLIANCE:
+ * - Read-only event emission (no backpressure)
+ * - Fire-and-forget semantics
+ * - No blocking on consumer processing
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Implementation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Notification Emitter implementation.
+ */
+export class NotificationEmitter {
+    callbacks = new Map();
+    subscribers = [];
+    webhooks = new Map();
+    _totalEmitted = 0;
+    _byType = new Map();
+    eventCounter = 0;
+    on(event, callback) {
+        let set = this.callbacks.get(event);
+        if (!set) {
+            set = new Set();
+            this.callbacks.set(event, set);
+        }
+        set.add(callback);
+    }
+    off(event, callback) {
+        const set = this.callbacks.get(event);
+        if (set) {
+            set.delete(callback);
+        }
+    }
+    subscribe(events) {
+        const self = this;
+        const queue = [];
+        let resolve = null;
+        let closed = false;
+        const subscriber = {
+            events: events ?? null,
+            push: (event) => {
+                if (closed)
+                    return;
+                if (resolve) {
+                    const r = resolve;
+                    resolve = null;
+                    r({ value: event, done: false });
+                }
+                else {
+                    queue.push(event);
+                }
+            },
+        };
+        this.subscribers.push(subscriber);
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    next() {
+                        if (closed) {
+                            return Promise.resolve({ value: undefined, done: true });
+                        }
+                        const queued = queue.shift();
+                        if (queued) {
+                            return Promise.resolve({ value: queued, done: false });
+                        }
+                        return new Promise((r) => {
+                            resolve = r;
+                        });
+                    },
+                    return() {
+                        closed = true;
+                        const idx = self.subscribers.indexOf(subscriber);
+                        if (idx !== -1) {
+                            self.subscribers.splice(idx, 1);
+                        }
+                        return Promise.resolve({ value: undefined, done: true });
+                    },
+                };
+            },
+        };
+    }
+    registerWebhook(config) {
+        const id = `webhook-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        this.webhooks.set(id, { ...config, id });
+        return id;
+    }
+    unregisterWebhook(id) {
+        this.webhooks.delete(id);
+    }
+    emit(type, payload) {
+        const event = {
+            type,
+            timestamp: Date.now(),
+            payload,
+            id: `evt-${++this.eventCounter}`,
+        };
+        // Update stats
+        this._totalEmitted++;
+        this._byType.set(type, (this._byType.get(type) ?? 0) + 1);
+        // Notify callbacks (fire-and-forget)
+        const callbacks = this.callbacks.get(type);
+        if (callbacks) {
+            for (const cb of callbacks) {
+                try {
+                    cb(event);
+                }
+                catch {
+                    // Silently ignore callback errors
+                }
+            }
+        }
+        // Notify subscribers
+        for (const sub of this.subscribers) {
+            if (sub.events === null || sub.events.includes(type)) {
+                sub.push(event);
+            }
+        }
+        // Dispatch webhooks (async, fire-and-forget)
+        for (const [, webhook] of this.webhooks) {
+            if (!webhook.events || webhook.events.length === 0 || webhook.events.includes(type)) {
+                this.dispatchWebhook(webhook, event).catch(() => {
+                    // Silently ignore webhook errors
+                });
+            }
+        }
+    }
+    get stats() {
+        const byType = {};
+        for (const [type, count] of this._byType) {
+            byType[type] = count;
+        }
+        return {
+            totalEmitted: this._totalEmitted,
+            byType: byType,
+            activeCallbacks: Array.from(this.callbacks.values()).reduce((sum, set) => sum + set.size, 0),
+            activeSubscribers: this.subscribers.length,
+            activeWebhooks: this.webhooks.size,
+        };
+    }
+    // ─── Private Methods ─────────────────────────────────────────────────────────
+    async dispatchWebhook(webhook, event) {
+        const body = JSON.stringify(event);
+        const headers = {
+            'Content-Type': 'application/json',
+            'User-Agent': 'Tracehound/1.0',
+            ...webhook.headers,
+        };
+        // Add HMAC signature if secret provided
+        if (webhook.secret) {
+            const { createHmac } = await import('node:crypto');
+            const signature = createHmac('sha256', webhook.secret).update(body).digest('hex');
+            headers['X-Tracehound-Signature'] = `sha256=${signature}`;
+        }
+        const maxAttempts = webhook.retry?.maxAttempts ?? 3;
+        const delayMs = webhook.retry?.delayMs ?? 1000;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                const response = await fetch(webhook.url, {
+                    method: 'POST',
+                    headers,
+                    body,
+                });
+                if (response.ok) {
+                    return;
+                }
+                // Retry on 5xx errors
+                if (response.status >= 500 && attempt < maxAttempts) {
+                    await this.sleep(delayMs * attempt);
+                    continue;
+                }
+                return; // Non-retryable error, give up silently
+            }
+            catch {
+                if (attempt < maxAttempts) {
+                    await this.sleep(delayMs * attempt);
+                    continue;
+                }
+                // Max attempts reached, give up silently
+            }
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Factory
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create a Notification Emitter instance.
+ */
+export function createNotificationEmitter() {
+    return new NotificationEmitter();
+}
+//# sourceMappingURL=notification-emitter.js.map

package/dist/core/notification-emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-emitter.js","sourceRoot":"","sources":["../../src/core/notification-emitter.ts"],"names":[],"mappings":"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"}

package/dist/core/process-adapter.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Hound Process Adapter - Platform-agnostic child process management.
+ *
+ * RFC-0000 REQUIREMENTS:
+ * - OS-level memory isolation
+ * - Independent crash domain
+ * - SIGKILL on kill()
+ * - No fork-specific semantics (spawn + pipe baseline)
+ *
+ * PLATFORM SUPPORT:
+ *
+ * | Feature              | Linux/macOS | Windows          |
+ * |----------------------|-------------|------------------|
+ * | Memory limit (V8)    | ✓ Enforced  | ✓ Enforced       |
+ * | SIGKILL              | ✓ Native    | ✓ TerminateProcess |
+ * | CPU limit            | ✗ N/A       | ✗ N/A            |
+ * | Network isolation    | Declared    | Declared         |
+ * | Filesystem isolation | Declared    | Declared         |
+ *
+ * WINDOWS LIMITATIONS:
+ * - Process constraints (network, filesystem, child spawn) are DECLARATIVE ONLY
+ * - No OS-level enforcement without external tools (Job Objects, containers)
+ * - Production recommendation: Use WSL2 or Docker for full isolation
+ *
+ * SECURITY MODEL:
+ * - Constraints are defense-in-depth, not security boundaries
+ * - Core security relies on: process separation, SIGKILL, timeout
+ * - Do NOT rely on constraint enforcement for security-critical isolation
+ */
+import { ChildProcess } from 'node:child_process';
+import { type MessageParser } from './hound-ipc.js';
+/**
+ * Handle to a spawned Hound process.
+ */
+export interface HoundHandle {
+    /** OS process ID */
+    readonly pid: number;
+    /** Internal process reference (not exposed) */
+    readonly _process: ChildProcess;
+    /** Message parser for this process */
+    readonly _parser: MessageParser;
+}
+/**
+ * Process exit callback.
+ */
+export type ExitCallback = (code: number | null, signal: string | null) => void;
+/**
+ * Message callback.
+ */
+export type MessageCallback = (payload: ArrayBuffer) => void;
+/**
+ * Process constraints (declarative, best-effort).
+ *
+ * NOTE: These are DECLARATIVE INTENT, not enforced guarantees.
+ * Platform-dependent. No security correctness depends on enforcement.
+ */
+export interface HoundProcessConstraints {
+    /** Max memory in MB (Linux: ulimit -v) */
+    maxMemoryMB?: number;
+    /** Network access (declared, not enforced in JS) */
+    networkAccess: false;
+    /** File system write (declared, not enforced in JS) */
+    fileSystemWrite: false;
+    /** Child process spawn (declared, not enforced in JS) */
+    childSpawn: false;
+}
+/**
+ * Default constraints (read-only).
+ */
+export declare const DEFAULT_CONSTRAINTS: Readonly<HoundProcessConstraints>;
+/**
+ * Hound Process Adapter interface.
+ *
+ * Abstracts child process management for:
+ * - Current: Node.js child_process
+ * - Future: WASM sandbox (same interface)
+ */
+export interface IHoundProcessAdapter {
+    /**
+     * Spawn a new Hound process.
+     *
+     * @param scriptPath - Path to Hound process script
+     * @param constraints - Process constraints (declarative)
+     * @returns Handle to spawned process
+     */
+    spawn(scriptPath: string, constraints?: Partial<HoundProcessConstraints>): HoundHandle;
+    /**
+     * Send binary payload to process.
+     *
+     * @param handle - Process handle
+     * @param payload - Binary payload
+     */
+    send(handle: HoundHandle, payload: ArrayBuffer): void;
+    /**
+     * Kill process immediately (SIGKILL).
+     *
+     * @param handle - Process handle
+     */
+    kill(handle: HoundHandle): void;
+    /**
+     * Register exit callback.
+     *
+     * @param handle - Process handle
+     * @param callback - Exit callback
+     */
+    onExit(handle: HoundHandle, callback: ExitCallback): void;
+    /**
+     * Register message callback.
+     *
+     * @param handle - Process handle
+     * @param callback - Message callback
+     */
+    onMessage(handle: HoundHandle, callback: MessageCallback): void;
+}
+/**
+ * Create a Hound Process Adapter.
+ *
+ * @returns Process adapter instance
+ */
+export declare function createProcessAdapter(): IHoundProcessAdapter;
+/**
+ * Mock process state for testing.
+ */
+interface MockProcessState {
+    pid: number;
+    alive: boolean;
+    exitCallbacks: ExitCallback[];
+    messageCallbacks: MessageCallback[];
+    receivedPayloads: ArrayBuffer[];
+}
+/**
+ * Create a mock adapter for testing.
+ * Does not spawn real processes.
+ *
+ * @returns Mock adapter with test utilities
+ */
+export declare function createMockAdapter(): IHoundProcessAdapter & {
+    /** Get all mock processes */
+    getMockProcesses(): Map<number, MockProcessState>;
+    /** Simulate process exit */
+    simulateExit(pid: number, code: number | null): void;
+    /** Simulate message from process */
+    simulateMessage(pid: number, payload: ArrayBuffer): void;
+};
+export {};
+//# sourceMappingURL=process-adapter.d.ts.map

package/dist/core/process-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-adapter.d.ts","sourceRoot":"","sources":["../../src/core/process-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAAE,YAAY,EAAS,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAsC,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAMvF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,oBAAoB;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;CAChC;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;AAE/E;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAA;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,aAAa,EAAE,KAAK,CAAA;IACpB,uDAAuD;IACvD,eAAe,EAAE,KAAK,CAAA;IACtB,yDAAyD;IACzD,UAAU,EAAE,KAAK,CAAA;CAClB;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,uBAAuB,CAKhE,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,GAAG,WAAW,CAAA;IAEtF;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAA;IAErD;;;;OAIG;IACH,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IAE/B;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAA;IAEzD;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAA;CAChE;AAMD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,oBAAoB,CA+D3D;AAMD;;GAEG;AACH,UAAU,gBAAgB;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,OAAO,CAAA;IACd,aAAa,EAAE,YAAY,EAAE,CAAA;IAC7B,gBAAgB,EAAE,eAAe,EAAE,CAAA;IACnC,gBAAgB,EAAE,WAAW,EAAE,CAAA;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,oBAAoB,GAAG;IAC1D,6BAA6B;IAC7B,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;IACjD,4BAA4B;IAC5B,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IACpD,oCAAoC;IACpC,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAA;CACzD,CA+EA"}

package/dist/core/process-adapter.js

@@ -0,0 +1,174 @@
+/**
+ * Hound Process Adapter - Platform-agnostic child process management.
+ *
+ * RFC-0000 REQUIREMENTS:
+ * - OS-level memory isolation
+ * - Independent crash domain
+ * - SIGKILL on kill()
+ * - No fork-specific semantics (spawn + pipe baseline)
+ *
+ * PLATFORM SUPPORT:
+ *
+ * | Feature              | Linux/macOS | Windows          |
+ * |----------------------|-------------|------------------|
+ * | Memory limit (V8)    | ✓ Enforced  | ✓ Enforced       |
+ * | SIGKILL              | ✓ Native    | ✓ TerminateProcess |
+ * | CPU limit            | ✗ N/A       | ✗ N/A            |
+ * | Network isolation    | Declared    | Declared         |
+ * | Filesystem isolation | Declared    | Declared         |
+ *
+ * WINDOWS LIMITATIONS:
+ * - Process constraints (network, filesystem, child spawn) are DECLARATIVE ONLY
+ * - No OS-level enforcement without external tools (Job Objects, containers)
+ * - Production recommendation: Use WSL2 or Docker for full isolation
+ *
+ * SECURITY MODEL:
+ * - Constraints are defense-in-depth, not security boundaries
+ * - Core security relies on: process separation, SIGKILL, timeout
+ * - Do NOT rely on constraint enforcement for security-critical isolation
+ */
+import { ChildProcess, spawn } from 'node:child_process';
+import { createMessageParser, encodeMessage } from './hound-ipc.js';
+/**
+ * Default constraints (read-only).
+ */
+export const DEFAULT_CONSTRAINTS = Object.freeze({
+    maxMemoryMB: 128,
+    networkAccess: false,
+    fileSystemWrite: false,
+    childSpawn: false,
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Implementation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Create a Hound Process Adapter.
+ *
+ * @returns Process adapter instance
+ */
+export function createProcessAdapter() {
+    return {
+        spawn(scriptPath, constraints) {
+            const mergedConstraints = { ...DEFAULT_CONSTRAINTS, ...constraints };
+            // Build spawn options
+            const execArgv = [];
+            // Memory limit (V8 heap)
+            if (mergedConstraints.maxMemoryMB) {
+                execArgv.push(`--max-old-space-size=${mergedConstraints.maxMemoryMB}`);
+            }
+            // Security flags
+            execArgv.push('--disable-proto=throw');
+            execArgv.push('--disallow-code-generation-from-strings');
+            // Spawn child process
+            // NOTE: Using spawn (not fork) for Windows compatibility
+            const child = spawn(process.execPath, [...execArgv, scriptPath], {
+                stdio: ['pipe', 'pipe', 'pipe'],
+                detached: false,
+                windowsHide: true,
+            });
+            if (!child.pid) {
+                throw new Error('Failed to spawn Hound process');
+            }
+            const parser = createMessageParser();
+            return {
+                pid: child.pid,
+                _process: child,
+                _parser: parser,
+            };
+        },
+        send(handle, payload) {
+            const message = encodeMessage(payload);
+            handle._process.stdin?.write(message);
+        },
+        kill(handle) {
+            // SIGKILL for immediate termination
+            handle._process.kill('SIGKILL');
+        },
+        onExit(handle, callback) {
+            handle._process.on('exit', (code, signal) => {
+                callback(code, signal);
+            });
+        },
+        onMessage(handle, callback) {
+            handle._process.stdout?.on('data', (chunk) => {
+                const messages = handle._parser.feed(chunk);
+                for (const payload of messages) {
+                    callback(payload);
+                }
+            });
+        },
+    };
+}
+/**
+ * Create a mock adapter for testing.
+ * Does not spawn real processes.
+ *
+ * @returns Mock adapter with test utilities
+ */
+export function createMockAdapter() {
+    const processes = new Map();
+    let nextPid = 1000;
+    const mockAdapter = {
+        spawn() {
+            const pid = nextPid++;
+            const state = {
+                pid,
+                alive: true,
+                exitCallbacks: [],
+                messageCallbacks: [],
+                receivedPayloads: [],
+            };
+            processes.set(pid, state);
+            return {
+                pid,
+                _process: { pid },
+                _parser: createMessageParser(),
+            };
+        },
+        send(handle, payload) {
+            const state = processes.get(handle.pid);
+            if (state?.alive) {
+                state.receivedPayloads.push(payload);
+            }
+        },
+        kill(handle) {
+            const state = processes.get(handle.pid);
+            if (state?.alive) {
+                state.alive = false;
+                for (const cb of state.exitCallbacks) {
+                    cb(null, 'SIGKILL');
+                }
+            }
+        },
+        onExit(handle, callback) {
+            const state = processes.get(handle.pid);
+            state?.exitCallbacks.push(callback);
+        },
+        onMessage(handle, callback) {
+            const state = processes.get(handle.pid);
+            state?.messageCallbacks.push(callback);
+        },
+        getMockProcesses() {
+            return processes;
+        },
+        simulateExit(pid, code) {
+            const state = processes.get(pid);
+            if (state?.alive) {
+                state.alive = false;
+                for (const cb of state.exitCallbacks) {
+                    cb(code, null);
+                }
+            }
+        },
+        simulateMessage(pid, payload) {
+            const state = processes.get(pid);
+            if (state?.alive) {
+                for (const cb of state.messageCallbacks) {
+                    cb(payload);
+                }
+            }
+        },
+    };
+    return mockAdapter;
+}
+//# sourceMappingURL=process-adapter.js.map