@tracehound/core 1.2.0

package/dist/core/evidence-factory.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Evidence Factory - creates Evidence instances with proper hash ownership.
+ *
+ * SECURITY INVARIANTS:
+ * - Factory owns all cryptographic operations
+ * - Agent MUST NOT compute hashes or signatures directly
+ * - Codec compression is internal to factory
+ * - Agent interface remains unchanged
+ */
+import type { TracehoundError } from '../types/errors.js';
+import type { Scent, ThreatSignal } from '../types/scent.js';
+import type { HotPathCodec } from '../utils/binary-codec.js';
+import { Evidence } from './evidence.js';
+/**
+ * Result of evidence creation.
+ */
+export type EvidenceCreationResult = {
+    ok: true;
+    /** Created evidence handle */
+    evidence: Evidence;
+    /** Generated signature */
+    signature: string;
+    /** Payload hash (of uncompressed canonical bytes) */
+    hash: string;
+    /** Size in bytes (compressed if codec provided) */
+    size: number;
+    /** Whether compression was applied */
+    compressed: boolean;
+} | {
+    ok: false;
+    /** Error that prevented creation */
+    error: TracehoundError;
+};
+/**
+ * Evidence factory options.
+ */
+export interface EvidenceFactoryOptions {
+    /**
+     * Optional codec for compression.
+     * If provided, evidence bytes will be compressed.
+     * Use createHotPathCodec() - NO decode access.
+     */
+    codec?: HotPathCodec;
+}
+/**
+ * Evidence factory interface.
+ */
+export interface IEvidenceFactory {
+    /**
+     * Create evidence from scent with threat signal.
+     *
+     * @param scent - The scent to create evidence from
+     * @param threat - Threat signal (category + severity)
+     * @param maxPayloadSize - Maximum allowed payload size (before compression)
+     * @returns Evidence creation result
+     */
+    create(scent: Scent, threat: ThreatSignal, maxPayloadSize: number): EvidenceCreationResult;
+}
+/**
+ * Evidence factory implementation.
+ *
+ * Responsibilities:
+ * 1. Encode payload (validation + canonical bytes)
+ * 2. Compute SHA-256 hash of canonical bytes (BEFORE compression)
+ * 3. Optionally compress bytes
+ * 4. Generate collision-resistant signature
+ * 5. Create Evidence instance with computed values
+ *
+ * SECURITY: Hash is computed on uncompressed bytes.
+ * This ensures signature determinism regardless of compression.
+ */
+export declare class EvidenceFactory implements IEvidenceFactory {
+    private readonly codec;
+    constructor(options?: EvidenceFactoryOptions);
+    create(scent: Scent, threat: ThreatSignal, maxPayloadSize: number): EvidenceCreationResult;
+    private isTracehoundError;
+}
+/**
+ * Create an evidence factory instance.
+ * Factory function for dependency injection.
+ *
+ * @param options - Optional configuration including codec
+ */
+export declare function createEvidenceFactory(options?: EvidenceFactoryOptions): IEvidenceFactory;
+//# sourceMappingURL=evidence-factory.d.ts.map

package/dist/core/evidence-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-factory.d.ts","sourceRoot":"","sources":["../../src/core/evidence-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAG5D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IACE,EAAE,EAAE,IAAI,CAAA;IACR,8BAA8B;IAC9B,QAAQ,EAAE,QAAQ,CAAA;IAClB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAA;IACZ,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAA;IACZ,sCAAsC;IACtC,UAAU,EAAE,OAAO,CAAA;CACpB,GACD;IACE,EAAE,EAAE,KAAK,CAAA;IACT,oCAAoC;IACpC,KAAK,EAAE,eAAe,CAAA;CACvB,CAAA;AAEL;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,GAAG,sBAAsB,CAAA;CAC3F;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;gBAEpC,OAAO,GAAE,sBAA2B;IAIhD,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,GAAG,sBAAsB;IAgE1F,OAAO,CAAC,iBAAiB;CAS1B;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,sBAA2B,GAAG,gBAAgB,CAE5F"}

package/dist/core/evidence-factory.js

@@ -0,0 +1,96 @@
+/**
+ * Evidence Factory - creates Evidence instances with proper hash ownership.
+ *
+ * SECURITY INVARIANTS:
+ * - Factory owns all cryptographic operations
+ * - Agent MUST NOT compute hashes or signatures directly
+ * - Codec compression is internal to factory
+ * - Agent interface remains unchanged
+ */
+import { encodePayload } from '../utils/encode.js';
+import { hashBuffer } from '../utils/hash.js';
+import { Evidence } from './evidence.js';
+/**
+ * Evidence factory implementation.
+ *
+ * Responsibilities:
+ * 1. Encode payload (validation + canonical bytes)
+ * 2. Compute SHA-256 hash of canonical bytes (BEFORE compression)
+ * 3. Optionally compress bytes
+ * 4. Generate collision-resistant signature
+ * 5. Create Evidence instance with computed values
+ *
+ * SECURITY: Hash is computed on uncompressed bytes.
+ * This ensures signature determinism regardless of compression.
+ */
+export class EvidenceFactory {
+    codec;
+    constructor(options = {}) {
+        this.codec = options.codec;
+    }
+    create(scent, threat, maxPayloadSize) {
+        try {
+            // Step 1: Encode payload with validation
+            const encoded = encodePayload(scent.payload, maxPayloadSize);
+            // Step 2: Compute hash of canonical bytes (BEFORE compression)
+            // This ensures signature determinism
+            const hash = hashBuffer(encoded.bytes);
+            // Step 3: Generate signature (category + hash)
+            const signature = `${threat.category}:${hash}`;
+            // Step 4: Optionally compress bytes
+            let finalBytes;
+            let compressed = false;
+            if (this.codec) {
+                finalBytes = this.codec.encode(encoded.bytes);
+                compressed = true;
+            }
+            else {
+                finalBytes = encoded.bytes;
+            }
+            // Step 5: Create Evidence instance
+            const evidence = new Evidence(finalBytes.buffer.slice(finalBytes.byteOffset, finalBytes.byteOffset + finalBytes.byteLength), signature, hash, threat.severity, scent.timestamp, compressed);
+            return {
+                ok: true,
+                evidence,
+                signature,
+                hash,
+                size: finalBytes.length,
+                compressed,
+            };
+        }
+        catch (error) {
+            // Convert to TracehoundError if not already
+            if (this.isTracehoundError(error)) {
+                return { ok: false, error };
+            }
+            // Wrap unknown error
+            return {
+                ok: false,
+                error: {
+                    state: 'agent',
+                    code: 'EVIDENCE_CREATION_FAILED',
+                    message: error instanceof Error ? error.message : 'Unknown error',
+                    context: { scentId: scent.id },
+                    recoverable: false,
+                },
+            };
+        }
+    }
+    isTracehoundError(error) {
+        return (typeof error === 'object' &&
+            error !== null &&
+            'state' in error &&
+            'code' in error &&
+            'message' in error);
+    }
+}
+/**
+ * Create an evidence factory instance.
+ * Factory function for dependency injection.
+ *
+ * @param options - Optional configuration including codec
+ */
+export function createEvidenceFactory(options = {}) {
+    return new EvidenceFactory(options);
+}
+//# sourceMappingURL=evidence-factory.js.map

package/dist/core/evidence-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-factory.js","sourceRoot":"","sources":["../../src/core/evidence-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAoDxC;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,eAAe;IACT,KAAK,CAA0B;IAEhD,YAAY,UAAkC,EAAE;QAC9C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAA;IAC5B,CAAC;IAED,MAAM,CAAC,KAAY,EAAE,MAAoB,EAAE,cAAsB;QAC/D,IAAI,CAAC;YACH,yCAAyC;YACzC,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,OAAO,EAAE,cAAc,CAAC,CAAA;YAE5D,+DAA+D;YAC/D,qCAAqC;YACrC,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;YAEtC,+CAA+C;YAC/C,MAAM,SAAS,GAAG,GAAG,MAAM,CAAC,QAAQ,IAAI,IAAI,EAAE,CAAA;YAE9C,oCAAoC;YACpC,IAAI,UAAsB,CAAA;YAC1B,IAAI,UAAU,GAAG,KAAK,CAAA;YAEtB,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBACf,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;gBAC7C,UAAU,GAAG,IAAI,CAAA;YACnB,CAAC;iBAAM,CAAC;gBACN,UAAU,GAAG,OAAO,CAAC,KAAK,CAAA;YAC5B,CAAC;YAED,mCAAmC;YACnC,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAC3B,UAAU,CAAC,MAAM,CAAC,KAAK,CACrB,UAAU,CAAC,UAAU,EACrB,UAAU,CAAC,UAAU,GAAG,UAAU,CAAC,UAAU,CAC/B,EAChB,SAAS,EACT,IAAI,EACJ,MAAM,CAAC,QAAQ,EACf,KAAK,CAAC,SAAS,EACf,UAAU,CACX,CAAA;YAED,OAAO;gBACL,EAAE,EAAE,IAAI;gBACR,QAAQ;gBACR,SAAS;gBACT,IAAI;gBACJ,IAAI,EAAE,UAAU,CAAC,MAAM;gBACvB,UAAU;aACX,CAAA;QACH,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,4CAA4C;YAC5C,IAAI,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;gBAClC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAA;YAC7B,CAAC;YAED,qBAAqB;YACrB,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,KAAK,EAAE;oBACL,KAAK,EAAE,OAAO;oBACd,IAAI,EAAE,0BAA0B;oBAChC,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;oBACjE,OAAO,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,EAAE;oBAC9B,WAAW,EAAE,KAAK;iBACnB;aACF,CAAA;QACH,CAAC;IACH,CAAC;IAEO,iBAAiB,CAAC,KAAc;QACtC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;YACzB,KAAK,KAAK,IAAI;YACd,OAAO,IAAI,KAAK;YAChB,MAAM,IAAI,KAAK;YACf,SAAS,IAAI,KAAK,CACnB,CAAA;IACH,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAkC,EAAE;IACxE,OAAO,IAAI,eAAe,CAAC,OAAO,CAAC,CAAA;AACrC,CAAC"}

package/dist/core/evidence.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Evidence class - quarantined threat evidence with ownership semantics.
+ *
+ * Phase 2 implementation.
+ */
+import type { Severity } from '../types/common.js';
+import type { EvacuateRecord, EvidenceHandle, NeutralizationRecord } from '../types/evidence.js';
+/**
+ * Evidence class implementing EvidenceHandle interface.
+ * Provides ownership-based access to quarantined threat data.
+ */
+export declare class Evidence implements EvidenceHandle {
+    private readonly _signature;
+    private readonly _expectedHash;
+    private readonly _severity;
+    private readonly _captured;
+    private _bytes;
+    private _disposed;
+    private readonly _compressed;
+    constructor(bytes: ArrayBuffer, _signature: string, _expectedHash: string, _severity: Severity, _captured: number, compressed?: boolean);
+    get bytes(): ArrayBuffer;
+    get size(): number;
+    get hash(): string;
+    get signature(): string;
+    get captured(): number;
+    get severity(): Severity;
+    get disposed(): boolean;
+    /**
+     * Transfer ownership of bytes.
+     * Handle becomes disposed after transfer.
+     */
+    transfer(): ArrayBuffer;
+    /**
+     * Atomically snapshot and destroy evidence.
+     * Returns neutralization record for audit chain.
+     *
+     * @param previousHash - Last hash in audit chain
+     */
+    neutralize(previousHash: string): NeutralizationRecord;
+    /**
+     * Move evidence to cold storage.
+     * Returns evacuation record.
+     *
+     * @param destination - Cold storage URL
+     */
+    evacuate(destination: string): EvacuateRecord;
+}
+//# sourceMappingURL=evidence.d.ts.map

package/dist/core/evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../src/core/evidence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAElD,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAIhG;;;GAGG;AACH,qBAAa,QAAS,YAAW,cAAc;IAO3C,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAT5B,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,SAAS,CAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAGnC,KAAK,EAAE,WAAW,EACD,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,QAAQ,EACnB,SAAS,EAAE,MAAM,EAClC,UAAU,GAAE,OAAe;IA2B7B,IAAI,KAAK,IAAI,WAAW,CAKvB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,QAAQ,IAAI,QAAQ,CAEvB;IAED,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAID;;;OAGG;IACH,QAAQ,IAAI,WAAW;IAYvB;;;;;OAKG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB;IAwBtD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc;CAqB9C"}

package/dist/core/evidence.js

@@ -0,0 +1,135 @@
+/**
+ * Evidence class - quarantined threat evidence with ownership semantics.
+ *
+ * Phase 2 implementation.
+ */
+import { Errors } from '../types/errors.js';
+import { hashBuffer } from '../utils/hash.js';
+import { generateSecureId } from '../utils/id.js';
+/**
+ * Evidence class implementing EvidenceHandle interface.
+ * Provides ownership-based access to quarantined threat data.
+ */
+export class Evidence {
+    _signature;
+    _expectedHash;
+    _severity;
+    _captured;
+    _bytes;
+    _disposed = false;
+    _compressed;
+    constructor(bytes, _signature, _expectedHash, _severity, _captured, compressed = false) {
+        this._signature = _signature;
+        this._expectedHash = _expectedHash;
+        this._severity = _severity;
+        this._captured = _captured;
+        // Validate bytes type
+        if (!(bytes instanceof ArrayBuffer)) {
+            throw Errors.invalidBytesType();
+        }
+        // Validate non-empty
+        if (bytes.byteLength === 0) {
+            throw Errors.emptyEvidence();
+        }
+        // Verify hash matches bytes ONLY for uncompressed evidence
+        // For compressed evidence, hash is of uncompressed content (per RFC)
+        if (!compressed) {
+            const actualHash = hashBuffer(bytes);
+            if (actualHash !== _expectedHash) {
+                throw Errors.hashMismatch(_expectedHash, actualHash);
+            }
+        }
+        this._bytes = bytes;
+        this._compressed = compressed;
+    }
+    // ─── Getters ────────────────────────────────────────────────────────────────
+    get bytes() {
+        if (this._disposed) {
+            throw Errors.evidenceAlreadyDisposed(this._signature);
+        }
+        return this._bytes;
+    }
+    get size() {
+        return this._bytes?.byteLength ?? 0;
+    }
+    get hash() {
+        return this._expectedHash;
+    }
+    get signature() {
+        return this._signature;
+    }
+    get captured() {
+        return this._captured;
+    }
+    get severity() {
+        return this._severity;
+    }
+    get disposed() {
+        return this._disposed;
+    }
+    // ─── Operations ─────────────────────────────────────────────────────────────
+    /**
+     * Transfer ownership of bytes.
+     * Handle becomes disposed after transfer.
+     */
+    transfer() {
+        if (this._disposed) {
+            throw Errors.evidenceAlreadyDisposed(this._signature);
+        }
+        const bytes = this._bytes;
+        this._bytes = null;
+        this._disposed = true;
+        return bytes;
+    }
+    /**
+     * Atomically snapshot and destroy evidence.
+     * Returns neutralization record for audit chain.
+     *
+     * @param previousHash - Last hash in audit chain
+     */
+    neutralize(previousHash) {
+        if (this._disposed) {
+            throw Errors.evidenceAlreadyDisposed(this._signature);
+        }
+        // ATOMIC: Snapshot BEFORE any mutation
+        const record = {
+            id: generateSecureId(),
+            signature: this._signature,
+            hash: this._expectedHash,
+            size: this._bytes.byteLength,
+            status: 'neutralized',
+            timestamp: Date.now(),
+            previousHash,
+        };
+        // ATOMIC: Destroy immediately (no async, no gaps)
+        this._bytes = null;
+        this._disposed = true;
+        // Return snapshot
+        return record;
+    }
+    /**
+     * Move evidence to cold storage.
+     * Returns evacuation record.
+     *
+     * @param destination - Cold storage URL
+     */
+    evacuate(destination) {
+        if (this._disposed) {
+            throw Errors.evidenceAlreadyDisposed(this._signature);
+        }
+        // ATOMIC: Snapshot BEFORE any mutation
+        const record = {
+            id: generateSecureId(),
+            signature: this._signature,
+            destination,
+            timestamp: Date.now(),
+            compressed: false, // TODO: Phase 3 compression
+            size: this._bytes.byteLength,
+        };
+        // ATOMIC: Destroy immediately
+        this._bytes = null;
+        this._disposed = true;
+        return record;
+    }
+}
+//# sourceMappingURL=evidence.js.map

package/dist/core/evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../src/core/evidence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAE3C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAEjD;;;GAGG;AACH,MAAM,OAAO,QAAQ;IAOA;IACA;IACA;IACA;IATX,MAAM,CAAoB;IAC1B,SAAS,GAAY,KAAK,CAAA;IACjB,WAAW,CAAS;IAErC,YACE,KAAkB,EACD,UAAkB,EAClB,aAAqB,EACrB,SAAmB,EACnB,SAAiB,EAClC,aAAsB,KAAK;QAJV,eAAU,GAAV,UAAU,CAAQ;QAClB,kBAAa,GAAb,aAAa,CAAQ;QACrB,cAAS,GAAT,SAAS,CAAU;QACnB,cAAS,GAAT,SAAS,CAAQ;QAGlC,sBAAsB;QACtB,IAAI,CAAC,CAAC,KAAK,YAAY,WAAW,CAAC,EAAE,CAAC;YACpC,MAAM,MAAM,CAAC,gBAAgB,EAAE,CAAA;QACjC,CAAC;QAED,qBAAqB;QACrB,IAAI,KAAK,CAAC,UAAU,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,MAAM,CAAC,aAAa,EAAE,CAAA;QAC9B,CAAC;QAED,2DAA2D;QAC3D,qEAAqE;QACrE,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,CAAA;YACpC,IAAI,UAAU,KAAK,aAAa,EAAE,CAAC;gBACjC,MAAM,MAAM,CAAC,YAAY,CAAC,aAAa,EAAE,UAAU,CAAC,CAAA;YACtD,CAAC;QACH,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,KAAK,CAAA;QACnB,IAAI,CAAC,WAAW,GAAG,UAAU,CAAA;IAC/B,CAAC;IAED,+EAA+E;IAE/E,IAAI,KAAK;QACP,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,MAAM,CAAC,uBAAuB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QACvD,CAAC;QACD,OAAO,IAAI,CAAC,MAAO,CAAA;IACrB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,EAAE,UAAU,IAAI,CAAC,CAAA;IACrC,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,aAAa,CAAA;IAC3B,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,UAAU,CAAA;IACxB,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,SAAS,CAAA;IACvB,CAAC;IAED,+EAA+E;IAE/E;;;OAGG;IACH,QAAQ;QACN,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,MAAM,CAAC,uBAAuB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QACvD,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,MAAO,CAAA;QAC1B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;QAClB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAA;QAErB,OAAO,KAAK,CAAA;IACd,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,YAAoB;QAC7B,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,MAAM,CAAC,uBAAuB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QACvD,CAAC;QAED,uCAAuC;QACvC,MAAM,MAAM,GAAyB;YACnC,EAAE,EAAE,gBAAgB,EAAE;YACtB,SAAS,EAAE,IAAI,CAAC,UAAU;YAC1B,IAAI,EAAE,IAAI,CAAC,aAAa;YACxB,IAAI,EAAE,IAAI,CAAC,MAAO,CAAC,UAAU;YAC7B,MAAM,EAAE,aAAa;YACrB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,YAAY;SACb,CAAA;QAED,kDAAkD;QAClD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;QAClB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAA;QAErB,kBAAkB;QAClB,OAAO,MAAM,CAAA;IACf,CAAC;IAED;;;;;OAKG;IACH,QAAQ,CAAC,WAAmB;QAC1B,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,MAAM,CAAC,uBAAuB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QACvD,CAAC;QAED,uCAAuC;QACvC,MAAM,MAAM,GAAmB;YAC7B,EAAE,EAAE,gBAAgB,EAAE;YACtB,SAAS,EAAE,IAAI,CAAC,UAAU;YAC1B,WAAW;YACX,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,UAAU,EAAE,KAAK,EAAE,4BAA4B;YAC/C,IAAI,EAAE,IAAI,CAAC,MAAO,CAAC,UAAU;SAC9B,CAAA;QAED,8BAA8B;QAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;QAClB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAA;QAErB,OAAO,MAAM,CAAA;IACf,CAAC;CACF"}

package/dist/core/fail-safe.d.ts

@@ -0,0 +1,149 @@
+/**
+ * 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)
+ */
+/**
+ * Panic levels.
+ */
+export type PanicLevel = 'warning' | 'critical' | 'emergency';
+/**
+ * Panic trigger reasons.
+ */
+export type PanicReason = 'memory_threshold' | 'quarantine_capacity' | 'error_rate' | 'process_exhaustion' | 'manual';
+/**
+ * Panic event payload.
+ */
+export interface PanicEvent {
+    /** Panic level */
+    level: PanicLevel;
+    /** Trigger reason */
+    reason: PanicReason;
+    /** Event timestamp */
+    timestamp: number;
+    /** Additional context */
+    context: {
+        /** Current value that triggered panic */
+        current?: number;
+        /** Threshold that was exceeded */
+        threshold?: number;
+        /** Additional details */
+        details?: string;
+    };
+}
+/**
+ * Panic callback signature.
+ */
+export type PanicCallback = (event: PanicEvent) => void | Promise<void>;
+/**
+ * Threshold configuration.
+ */
+export interface ThresholdConfig {
+    /** Warning threshold (0-1, percentage) */
+    warning: number;
+    /** Critical threshold (0-1, percentage) */
+    critical: number;
+    /** Emergency threshold (0-1, percentage) */
+    emergency: number;
+}
+/**
+ * Fail-safe configuration.
+ */
+export interface FailSafeConfig {
+    /** Memory usage thresholds */
+    memory: ThresholdConfig;
+    /** Quarantine capacity thresholds */
+    quarantine: ThresholdConfig;
+    /** Error rate thresholds (errors per minute) */
+    errorRate: ThresholdConfig;
+}
+/**
+ * Default thresholds.
+ */
+export declare const DEFAULT_FAIL_SAFE_CONFIG: FailSafeConfig;
+/**
+ * Fail-Safe Panic system.
+ */
+export declare class FailSafe {
+    private config;
+    private callbacks;
+    private panicHistory;
+    private readonly maxHistory;
+    constructor(config?: FailSafeConfig);
+    /**
+     * Register a callback for a panic level.
+     *
+     * @param level - Panic level to listen for
+     * @param callback - Callback function
+     */
+    on(level: PanicLevel, callback: PanicCallback): void;
+    /**
+     * Register a callback for all panic levels.
+     *
+     * @param callback - Callback function
+     */
+    onAny(callback: PanicCallback): void;
+    /**
+     * Check memory usage and trigger panic if needed.
+     *
+     * @param usedBytes - Current memory usage
+     * @param totalBytes - Total available memory
+     */
+    checkMemory(usedBytes: number, totalBytes: number): void;
+    /**
+     * Check quarantine capacity and trigger panic if needed.
+     *
+     * @param current - Current quarantine count
+     * @param max - Maximum quarantine capacity
+     */
+    checkQuarantine(current: number, max: number): void;
+    /**
+     * Check error rate and trigger panic if needed.
+     *
+     * @param errorsPerMinute - Current error rate
+     */
+    checkErrorRate(errorsPerMinute: number): void;
+    /**
+     * Manually trigger a panic.
+     *
+     * @param level - Panic level
+     * @param details - Optional details
+     */
+    panic(level: PanicLevel, details?: string): void;
+    /**
+     * Trigger a panic event.
+     *
+     * @param event - Panic event
+     */
+    trigger(event: PanicEvent): void;
+    /**
+     * Get panic history.
+     */
+    get history(): readonly PanicEvent[];
+    /**
+     * Get last panic event.
+     */
+    get lastPanic(): PanicEvent | undefined;
+    /**
+     * Determine panic level based on value and thresholds.
+     */
+    private determineLevel;
+}
+/**
+ * Create a fail-safe instance.
+ *
+ * @param config - Optional configuration
+ * @returns FailSafe instance
+ */
+export declare function createFailSafe(config?: Partial<FailSafeConfig>): FailSafe;
+//# sourceMappingURL=fail-safe.d.ts.map

package/dist/core/fail-safe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fail-safe.d.ts","sourceRoot":"","sources":["../../src/core/fail-safe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAA;AAE7D;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB,kBAAkB,GAClB,qBAAqB,GACrB,YAAY,GACZ,oBAAoB,GACpB,QAAQ,CAAA;AAEZ;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,kBAAkB;IAClB,KAAK,EAAE,UAAU,CAAA;IACjB,qBAAqB;IACrB,MAAM,EAAE,WAAW,CAAA;IACnB,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,yBAAyB;IACzB,OAAO,EAAE;QACP,yCAAyC;QACzC,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,kCAAkC;QAClC,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,yBAAyB;QACzB,OAAO,CAAC,EAAE,MAAM,CAAA;KACjB,CAAA;CACF;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAEvE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;IACf,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,MAAM,EAAE,eAAe,CAAA;IACvB,qCAAqC;IACrC,UAAU,EAAE,eAAe,CAAA;IAC3B,gDAAgD;IAChD,SAAS,EAAE,eAAe,CAAA;CAC3B;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,cAgBtC,CAAA;AAMD;;GAEG;AACH,qBAAa,QAAQ;IAUP,OAAO,CAAC,MAAM;IAT1B,OAAO,CAAC,SAAS,CAIf;IAEF,OAAO,CAAC,YAAY,CAAmB;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAM;gBAEb,MAAM,GAAE,cAAyC;IAErE;;;;;OAKG;IACH,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,GAAG,IAAI;IAIpD;;;;OAIG;IACH,KAAK,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAMpC;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAkBxD;;;;;OAKG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAkBnD;;;;OAIG;IACH,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI;IAiB7C;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAShD;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAuBhC;;OAEG;IACH,IAAI,OAAO,IAAI,SAAS,UAAU,EAAE,CAEnC;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,UAAU,GAAG,SAAS,CAEtC;IAED;;OAEG;IACH,OAAO,CAAC,cAAc;CAMvB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,QAAQ,CAQzE"}