@tracehound/core 1.2.0

package/dist/core/fail-safe.js

@@ -0,0 +1,217 @@
+/**
+ * Fail-Safe Panic - Threshold-triggered emergency callbacks.
+ *
+ * Provides hooks for emergency situations:
+ * - Memory threshold exceeded
+ * - Quarantine capacity critical
+ * - Error rate exceeded
+ * - Manual panic trigger
+ *
+ * DESIGN:
+ * - Panic levels: warning, critical, emergency
+ * - Each level can have multiple callbacks
+ * - Emergency triggers immediate flush and cleanup
+ * - All callbacks are non-blocking (fire-and-forget)
+ */
+/**
+ * Default thresholds.
+ */
+export const DEFAULT_FAIL_SAFE_CONFIG = {
+    memory: {
+        warning: 0.7, // 70%
+        critical: 0.85, // 85%
+        emergency: 0.95, // 95%
+    },
+    quarantine: {
+        warning: 0.7,
+        critical: 0.85,
+        emergency: 0.95,
+    },
+    errorRate: {
+        warning: 10, // 10 errors/min
+        critical: 50, // 50 errors/min
+        emergency: 100, // 100 errors/min
+    },
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Implementation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Fail-Safe Panic system.
+ */
+export class FailSafe {
+    config;
+    callbacks = new Map([
+        ['warning', []],
+        ['critical', []],
+        ['emergency', []],
+    ]);
+    panicHistory = [];
+    maxHistory = 100;
+    constructor(config = DEFAULT_FAIL_SAFE_CONFIG) {
+        this.config = config;
+    }
+    /**
+     * Register a callback for a panic level.
+     *
+     * @param level - Panic level to listen for
+     * @param callback - Callback function
+     */
+    on(level, callback) {
+        this.callbacks.get(level).push(callback);
+    }
+    /**
+     * Register a callback for all panic levels.
+     *
+     * @param callback - Callback function
+     */
+    onAny(callback) {
+        this.on('warning', callback);
+        this.on('critical', callback);
+        this.on('emergency', callback);
+    }
+    /**
+     * Check memory usage and trigger panic if needed.
+     *
+     * @param usedBytes - Current memory usage
+     * @param totalBytes - Total available memory
+     */
+    checkMemory(usedBytes, totalBytes) {
+        const ratio = usedBytes / totalBytes;
+        const level = this.determineLevel(ratio, this.config.memory);
+        if (level) {
+            this.trigger({
+                level,
+                reason: 'memory_threshold',
+                timestamp: Date.now(),
+                context: {
+                    current: ratio,
+                    threshold: this.config.memory[level],
+                    details: `Memory usage: ${(ratio * 100).toFixed(1)}%`,
+                },
+            });
+        }
+    }
+    /**
+     * Check quarantine capacity and trigger panic if needed.
+     *
+     * @param current - Current quarantine count
+     * @param max - Maximum quarantine capacity
+     */
+    checkQuarantine(current, max) {
+        const ratio = current / max;
+        const level = this.determineLevel(ratio, this.config.quarantine);
+        if (level) {
+            this.trigger({
+                level,
+                reason: 'quarantine_capacity',
+                timestamp: Date.now(),
+                context: {
+                    current: ratio,
+                    threshold: this.config.quarantine[level],
+                    details: `Quarantine: ${current}/${max}`,
+                },
+            });
+        }
+    }
+    /**
+     * Check error rate and trigger panic if needed.
+     *
+     * @param errorsPerMinute - Current error rate
+     */
+    checkErrorRate(errorsPerMinute) {
+        const level = this.determineLevel(errorsPerMinute, this.config.errorRate);
+        if (level) {
+            this.trigger({
+                level,
+                reason: 'error_rate',
+                timestamp: Date.now(),
+                context: {
+                    current: errorsPerMinute,
+                    threshold: this.config.errorRate[level],
+                    details: `Error rate: ${errorsPerMinute}/min`,
+                },
+            });
+        }
+    }
+    /**
+     * Manually trigger a panic.
+     *
+     * @param level - Panic level
+     * @param details - Optional details
+     */
+    panic(level, details) {
+        this.trigger({
+            level,
+            reason: 'manual',
+            timestamp: Date.now(),
+            context: details ? { details } : {},
+        });
+    }
+    /**
+     * Trigger a panic event.
+     *
+     * @param event - Panic event
+     */
+    trigger(event) {
+        // Add to history
+        this.panicHistory.push(event);
+        if (this.panicHistory.length > this.maxHistory) {
+            this.panicHistory.shift();
+        }
+        // Fire callbacks (non-blocking)
+        const callbacks = this.callbacks.get(event.level);
+        for (const callback of callbacks) {
+            try {
+                const result = callback(event);
+                if (result instanceof Promise) {
+                    result.catch(() => {
+                        // Swallow async errors - fail-safe must not throw
+                    });
+                }
+            }
+            catch {
+                // Swallow sync errors - fail-safe must not throw
+            }
+        }
+    }
+    /**
+     * Get panic history.
+     */
+    get history() {
+        return this.panicHistory;
+    }
+    /**
+     * Get last panic event.
+     */
+    get lastPanic() {
+        return this.panicHistory[this.panicHistory.length - 1];
+    }
+    /**
+     * Determine panic level based on value and thresholds.
+     */
+    determineLevel(value, thresholds) {
+        if (value >= thresholds.emergency)
+            return 'emergency';
+        if (value >= thresholds.critical)
+            return 'critical';
+        if (value >= thresholds.warning)
+            return 'warning';
+        return null;
+    }
+}
+/**
+ * Create a fail-safe instance.
+ *
+ * @param config - Optional configuration
+ * @returns FailSafe instance
+ */
+export function createFailSafe(config) {
+    const mergedConfig = {
+        memory: { ...DEFAULT_FAIL_SAFE_CONFIG.memory, ...config?.memory },
+        quarantine: { ...DEFAULT_FAIL_SAFE_CONFIG.quarantine, ...config?.quarantine },
+        errorRate: { ...DEFAULT_FAIL_SAFE_CONFIG.errorRate, ...config?.errorRate },
+    };
+    return new FailSafe(mergedConfig);
+}
+//# sourceMappingURL=fail-safe.js.map

package/dist/core/fail-safe.js.map

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

package/dist/core/hound-ipc.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Hound IPC - Binary length-prefixed protocol for child process communication.
+ *
+ * RFC-0000 REQUIREMENTS:
+ * - Length-prefixed binary over stdio
+ * - JSON encoding is explicitly forbidden
+ * - No retry semantics
+ * - Fire-and-forget
+ */
+/**
+ * Message types that can be sent over IPC.
+ * Matches RFC-0000 HoundMessage types.
+ */
+export type HoundMessageType = 'status' | 'metrics';
+export type HoundStatus = 'processing' | 'complete' | 'error';
+export interface HoundStatusMessage {
+    type: 'status';
+    state: HoundStatus;
+    error?: string;
+}
+export interface HoundMetricsMessage {
+    type: 'metrics';
+    processingTime: number;
+    memoryUsed: number;
+}
+export type HoundMessage = HoundStatusMessage | HoundMetricsMessage;
+/**
+ * Parsed message from IPC stream.
+ */
+export interface ParsedMessage {
+    payload: ArrayBuffer;
+    bytesConsumed: number;
+}
+/**
+ * Encode a payload with length prefix.
+ *
+ * Format: [4 bytes length BE][N bytes payload]
+ *
+ * @param payload - Raw payload bytes
+ * @returns Length-prefixed buffer
+ */
+export declare function encodeMessage(payload: ArrayBuffer): Buffer;
+/**
+ * Encode a HoundMessage to binary.
+ *
+ * @param message - Message to encode
+ * @returns Length-prefixed buffer
+ */
+export declare function encodeHoundMessage(message: HoundMessage): Buffer;
+/**
+ * Try to parse a message from a buffer.
+ * Handles partial buffers gracefully.
+ *
+ * @param buffer - Input buffer (may contain partial message)
+ * @returns Parsed message or null if incomplete
+ */
+export declare function tryParseMessage(buffer: Buffer): ParsedMessage | null;
+/**
+ * Decode a HoundMessage from binary payload.
+ *
+ * @param payload - Raw payload bytes (without length prefix)
+ * @returns Decoded message
+ */
+export declare function decodeHoundMessage(payload: ArrayBuffer): HoundMessage;
+/**
+ * Streaming message parser.
+ * Handles partial buffers and backpressure.
+ */
+export interface MessageParser {
+    /**
+     * Feed data into parser.
+     * @param chunk - New data chunk
+     * @returns Array of complete messages
+     */
+    feed(chunk: Buffer): ArrayBuffer[];
+    /**
+     * Get remaining buffered bytes.
+     */
+    readonly bufferedBytes: number;
+    /**
+     * Reset parser state.
+     */
+    reset(): void;
+}
+/**
+ * Create a streaming message parser.
+ *
+ * @returns Message parser instance
+ */
+export declare function createMessageParser(): MessageParser;
+//# sourceMappingURL=hound-ipc.d.ts.map

package/dist/core/hound-ipc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hound-ipc.d.ts","sourceRoot":"","sources":["../../src/core/hound-ipc.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,SAAS,CAAA;AAEnD,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,UAAU,GAAG,OAAO,CAAA;AAE7D,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,QAAQ,CAAA;IACd,KAAK,EAAE,WAAW,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,CAAA;IACf,cAAc,EAAE,MAAM,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,MAAM,YAAY,GAAG,kBAAkB,GAAG,mBAAmB,CAAA;AAEnE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,WAAW,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;CACtB;AAgBD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAiB1D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CA8BhE;AAmBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CA2BpE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,YAAY,CAqCrE;AAmBD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,EAAE,CAAA;IAElC;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAE9B;;OAEG;IACH,KAAK,IAAI,IAAI,CAAA;CACd;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CA8BnD"}

package/dist/core/hound-ipc.js

@@ -0,0 +1,196 @@
+/**
+ * Hound IPC - Binary length-prefixed protocol for child process communication.
+ *
+ * RFC-0000 REQUIREMENTS:
+ * - Length-prefixed binary over stdio
+ * - JSON encoding is explicitly forbidden
+ * - No retry semantics
+ * - Fire-and-forget
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+/** Length prefix size in bytes (32-bit BE) */
+const LENGTH_PREFIX_SIZE = 4;
+/** Maximum message size (1MB) */
+const MAX_MESSAGE_SIZE = 1024 * 1024;
+// ─────────────────────────────────────────────────────────────────────────────
+// Encoding
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Encode a payload with length prefix.
+ *
+ * Format: [4 bytes length BE][N bytes payload]
+ *
+ * @param payload - Raw payload bytes
+ * @returns Length-prefixed buffer
+ */
+export function encodeMessage(payload) {
+    const payloadBuffer = Buffer.from(payload);
+    const length = payloadBuffer.length;
+    if (length > MAX_MESSAGE_SIZE) {
+        throw new Error(`Message too large: ${length} > ${MAX_MESSAGE_SIZE}`);
+    }
+    const result = Buffer.allocUnsafe(LENGTH_PREFIX_SIZE + length);
+    // Write length as 32-bit BE
+    result.writeUInt32BE(length, 0);
+    // Copy payload
+    payloadBuffer.copy(result, LENGTH_PREFIX_SIZE);
+    return result;
+}
+/**
+ * Encode a HoundMessage to binary.
+ *
+ * @param message - Message to encode
+ * @returns Length-prefixed buffer
+ */
+export function encodeHoundMessage(message) {
+    // Use minimal binary encoding (not JSON)
+    // Format: [1 byte type][payload bytes]
+    if (message.type === 'status') {
+        // Type 0x01 = status
+        // [1 byte type][1 byte state][optional error string]
+        const stateCode = encodeStatusState(message.state);
+        const errorBytes = message.error ? Buffer.from(message.error, 'utf8') : Buffer.alloc(0);
+        const payload = Buffer.allocUnsafe(2 + errorBytes.length);
+        payload[0] = 0x01; // type: status
+        payload[1] = stateCode;
+        errorBytes.copy(payload, 2);
+        return encodeMessage(payload.buffer.slice(payload.byteOffset, payload.byteOffset + payload.length));
+    }
+    else {
+        // Type 0x02 = metrics
+        // [1 byte type][8 bytes processingTime][8 bytes memoryUsed]
+        const payload = Buffer.allocUnsafe(17);
+        payload[0] = 0x02; // type: metrics
+        payload.writeDoubleBE(message.processingTime, 1);
+        payload.writeDoubleBE(message.memoryUsed, 9);
+        return encodeMessage(payload.buffer.slice(payload.byteOffset, payload.byteOffset + payload.length));
+    }
+}
+function encodeStatusState(state) {
+    switch (state) {
+        case 'processing':
+            return 0x01;
+        case 'complete':
+            return 0x02;
+        case 'error':
+            return 0x03;
+        default:
+            return 0x00;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Decoding
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Try to parse a message from a buffer.
+ * Handles partial buffers gracefully.
+ *
+ * @param buffer - Input buffer (may contain partial message)
+ * @returns Parsed message or null if incomplete
+ */
+export function tryParseMessage(buffer) {
+    // Need at least length prefix
+    if (buffer.length < LENGTH_PREFIX_SIZE) {
+        return null;
+    }
+    const length = buffer.readUInt32BE(0);
+    // Validate length
+    if (length > MAX_MESSAGE_SIZE) {
+        throw new Error(`Invalid message length: ${length}`);
+    }
+    const totalSize = LENGTH_PREFIX_SIZE + length;
+    // Check if we have full message
+    if (buffer.length < totalSize) {
+        return null;
+    }
+    // Extract payload
+    const payloadSlice = buffer.subarray(LENGTH_PREFIX_SIZE, totalSize);
+    return {
+        payload: new Uint8Array(payloadSlice).buffer,
+        bytesConsumed: totalSize,
+    };
+}
+/**
+ * Decode a HoundMessage from binary payload.
+ *
+ * @param payload - Raw payload bytes (without length prefix)
+ * @returns Decoded message
+ */
+export function decodeHoundMessage(payload) {
+    const buffer = Buffer.from(payload);
+    if (buffer.length < 1) {
+        throw new Error('Empty message payload');
+    }
+    const type = buffer[0];
+    if (type === 0x01) {
+        // Status message
+        if (buffer.length < 2) {
+            throw new Error('Invalid status message: too short');
+        }
+        const stateCode = buffer[1] ?? 0;
+        const state = decodeStatusState(stateCode);
+        const errorStr = buffer.length > 2 ? buffer.subarray(2).toString('utf8') : undefined;
+        const result = { type: 'status', state };
+        if (errorStr) {
+            result.error = errorStr;
+        }
+        return result;
+    }
+    else if (type === 0x02) {
+        // Metrics message
+        if (buffer.length < 17) {
+            throw new Error('Invalid metrics message: too short');
+        }
+        const processingTime = buffer.readDoubleBE(1);
+        const memoryUsed = buffer.readDoubleBE(9);
+        return { type: 'metrics', processingTime, memoryUsed };
+    }
+    else {
+        throw new Error(`Unknown message type: ${type}`);
+    }
+}
+function decodeStatusState(code) {
+    switch (code) {
+        case 0x01:
+            return 'processing';
+        case 0x02:
+            return 'complete';
+        case 0x03:
+            return 'error';
+        default:
+            throw new Error(`Unknown status state: ${code}`);
+    }
+}
+/**
+ * Create a streaming message parser.
+ *
+ * @returns Message parser instance
+ */
+export function createMessageParser() {
+    let buffer = Buffer.alloc(0);
+    return {
+        feed(chunk) {
+            // Append chunk to buffer
+            buffer = Buffer.concat([buffer, chunk]);
+            const messages = [];
+            // Parse all complete messages
+            while (true) {
+                const result = tryParseMessage(buffer);
+                if (!result)
+                    break;
+                messages.push(result.payload);
+                buffer = buffer.subarray(result.bytesConsumed);
+            }
+            return messages;
+        },
+        get bufferedBytes() {
+            return buffer.length;
+        },
+        reset() {
+            buffer = Buffer.alloc(0);
+        },
+    };
+}
+//# sourceMappingURL=hound-ipc.js.map

package/dist/core/hound-ipc.js.map

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

package/dist/core/hound-pool.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Hound Pool - Process-based isolation pool for evidence processing.
+ *
+ * RFC-0000 CRITICAL INVARIANTS:
+ * - activate() returns void, NOT Promise (Agent NEVER awaits)
+ * - OS-level process isolation (child processes, not threads)
+ * - Pre-spawned processes with jittered rotation
+ * - Timeout + SIGKILL for stuck processes
+ * - Binary IPC over stdio (no JSON)
+ *
+ * INVARIANT: activeProcesses <= totalProcesses
+ * activeProcesses reflects OS-level active child processes
+ */
+import type { Evidence } from './evidence.js';
+import { createMockAdapter, type HoundProcessConstraints, type IHoundProcessAdapter } from './process-adapter.js';
+/**
+ * Hound execution result.
+ * Delivered via internal queue, NOT via Promise to Agent.
+ */
+export interface HoundResult {
+    /** Evidence signature */
+    signature: string;
+    /** Execution status */
+    status: 'processed' | 'timeout' | 'error';
+    /** Processing duration in ms */
+    durationMs: number;
+    /** Process ID that processed this */
+    processId: string;
+    /** Error message if status is 'error' */
+    error?: string;
+}
+/**
+ * Hound pool statistics (immutable snapshot).
+ *
+ * INVARIANT: activeProcesses <= totalProcesses
+ */
+export interface HoundPoolStats {
+    /** Number of active processes (OS-level) */
+    activeProcesses: number;
+    /** Total processes in pool */
+    totalProcesses: number;
+    /** Total activations */
+    totalActivations: number;
+    /** Total timeouts */
+    totalTimeouts: number;
+    /** Total errors */
+    totalErrors: number;
+    /** Average processing time in ms */
+    avgProcessingMs: number;
+}
+/**
+ * Pool exhaustion action.
+ */
+export type PoolExhaustedAction = 'drop' | 'escalate' | 'defer';
+/**
+ * Hound pool configuration.
+ */
+export interface HoundPoolConfig {
+    /** Number of pre-spawned processes */
+    poolSize: number;
+    /** Timeout per process in ms */
+    timeout: number;
+    /** Jitter range for rotation in ms */
+    rotationJitterMs: number;
+    /** Action when pool exhausted (default: 'drop') */
+    onPoolExhausted?: PoolExhaustedAction;
+    /** Max queue size for 'defer' action (default: 100) */
+    deferQueueLimit?: number;
+    /** Process constraints (declarative, best-effort) */
+    processConstraints?: Partial<HoundProcessConstraints>;
+    /** Path to hound process script */
+    processScriptPath?: string;
+    /** Custom process adapter (for testing) */
+    adapter?: IHoundProcessAdapter;
+}
+/**
+ * Hound pool interface.
+ *
+ * CRITICAL: activate() returns void.
+ * Agent NEVER awaits Hound Pool.
+ */
+export interface IHoundPool {
+    /**
+     * Activate hound for evidence processing.
+     * Returns immediately. Result via onResult callback.
+     *
+     * @param evidence - Evidence to process
+     */
+    activate(evidence: Evidence): void;
+    /**
+     * Force terminate specific hound by signature.
+     *
+     * @param signature - Evidence signature to terminate
+     */
+    terminate(signature: string): void;
+    /**
+     * Get pool statistics (immutable snapshot).
+     */
+    readonly stats: Readonly<HoundPoolStats>;
+    /**
+     * Register result handler.
+     * Internal use only - NOT exposed to Agent.
+     */
+    onResult(handler: (result: HoundResult) => void): void;
+    /**
+     * Shutdown all processes.
+     */
+    shutdown(): void;
+}
+/**
+ * Hound Pool implementation.
+ *
+ * Uses child process isolation per RFC-0000 amendment.
+ */
+export declare class HoundPool implements IHoundPool {
+    private readonly config;
+    private readonly processes;
+    private readonly pendingQueue;
+    private readonly resultHandlers;
+    private readonly processingTimes;
+    private readonly adapter;
+    private readonly processScriptPath;
+    private readonly onPoolExhausted;
+    private readonly deferQueueLimit;
+    private _totalActivations;
+    private _totalTimeouts;
+    private _totalErrors;
+    constructor(config: HoundPoolConfig);
+    /**
+     * Process constraints (declarative, best-effort).
+     */
+    static readonly DEFAULT_CONSTRAINTS: Readonly<HoundProcessConstraints>;
+    activate(evidence: Evidence): void;
+    private handlePoolExhausted;
+    terminate(signature: string): void;
+    get stats(): Readonly<HoundPoolStats>;
+    onResult(handler: (result: HoundResult) => void): void;
+    shutdown(): void;
+    private createProcessState;
+    private findAvailableProcess;
+    private assignToProcess;
+    private handleProcessMessage;
+    private handleProcessExit;
+    private handleTimeout;
+    private terminateProcess;
+    private completeProcessing;
+    private processNextInQueue;
+    private emitResult;
+}
+/**
+ * Create a Hound Pool instance.
+ *
+ * @param config - Pool configuration
+ */
+export declare function createHoundPool(config: HoundPoolConfig): IHoundPool;
+export { createMockAdapter };
+//# sourceMappingURL=hound-pool.d.ts.map