claude-flow 3.28.0 → 3.29.0

package/v3/@claude-flow/guidance/dist/persistence.js

@@ -0,0 +1,464 @@
+/**
+ * Ledger Persistence Layer
+ *
+ * Connects the in-memory RunLedger to durable file-based storage using
+ * newline-delimited JSON (NDJSON). Provides append-only event logging,
+ * compaction, and lock-based concurrent access prevention.
+ *
+ * Storage layout:
+ *   {storagePath}/events.ndjson  - Newline-delimited JSON events
+ *   {storagePath}/index.json     - Metadata index (counts, timestamps, task IDs)
+ *   {storagePath}/.lock          - Lock file for concurrent access prevention
+ *
+ * @module @claude-flow/guidance/persistence
+ */
+import { mkdir, readFile, writeFile, appendFile, stat, unlink, rename } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { RunLedger } from './ledger.js';
+// ============================================================================
+// Default Configuration
+// ============================================================================
+const DEFAULT_PERSISTENCE_CONFIG = {
+    storagePath: '.claude-flow/guidance',
+    maxEvents: 10_000,
+    compactIntervalMs: 60 * 60 * 1000, // 1 hour
+    enableWAL: true,
+};
+// Lock file stale threshold: 30 seconds
+const LOCK_STALE_MS = 30_000;
+// ============================================================================
+// EventStore (Internal)
+// ============================================================================
+/**
+ * Low-level NDJSON-based event storage.
+ *
+ * Handles file I/O, append-only writes, range reads, compaction,
+ * and lock-based concurrent access prevention.
+ */
+export class EventStore {
+    eventsPath;
+    indexPath;
+    lockPath;
+    baseDir;
+    lockHolder = null;
+    constructor(storagePath) {
+        this.baseDir = storagePath;
+        this.eventsPath = join(storagePath, 'events.ndjson');
+        this.indexPath = join(storagePath, 'index.json');
+        this.lockPath = join(storagePath, '.lock');
+    }
+    /**
+     * Append a single event to the NDJSON file and update the index.
+     */
+    async append(event) {
+        await this.ensureDirectory();
+        const line = JSON.stringify(event) + '\n';
+        await appendFile(this.eventsPath, line, 'utf-8');
+        await this.updateIndex(event);
+    }
+    /**
+     * Read and parse all events from storage.
+     */
+    async readAll() {
+        if (!existsSync(this.eventsPath)) {
+            return [];
+        }
+        const content = await readFile(this.eventsPath, 'utf-8');
+        return this.parseNdjson(content);
+    }
+    /**
+     * Read events within a time range [startTime, endTime].
+     */
+    async readRange(startTime, endTime) {
+        const all = await this.readAll();
+        return all.filter(e => e.timestamp >= startTime && e.timestamp <= endTime);
+    }
+    /**
+     * Compact the event store to keep at most `maxEvents` events.
+     * Oldest events are evicted first. Rewrites the NDJSON file atomically.
+     *
+     * @returns The number of evicted events.
+     */
+    async compact(maxEvents) {
+        const events = await this.readAll();
+        if (events.length <= maxEvents) {
+            return 0;
+        }
+        // Sort by timestamp ascending, keep the newest maxEvents
+        events.sort((a, b) => a.timestamp - b.timestamp);
+        const evicted = events.length - maxEvents;
+        const kept = events.slice(evicted);
+        // Atomic rewrite: write to temp file, then rename
+        await this.ensureDirectory();
+        const tempPath = join(this.baseDir, `events.tmp.${randomUUID()}.ndjson`);
+        const content = kept.map(e => JSON.stringify(e)).join('\n') + (kept.length > 0 ? '\n' : '');
+        await writeFile(tempPath, content, 'utf-8');
+        await rename(tempPath, this.eventsPath);
+        // Rebuild index from kept events
+        await this.rebuildIndex(kept);
+        return evicted;
+    }
+    /**
+     * Atomically replace all events in storage with the given array.
+     * Rewrites the NDJSON file and rebuilds the index.
+     */
+    async writeAll(events) {
+        await this.ensureDirectory();
+        const tempPath = join(this.baseDir, `events.tmp.${randomUUID()}.ndjson`);
+        const content = events.map(e => JSON.stringify(e)).join('\n') + (events.length > 0 ? '\n' : '');
+        await writeFile(tempPath, content, 'utf-8');
+        await rename(tempPath, this.eventsPath);
+        await this.rebuildIndex(events);
+    }
+    /**
+     * Get storage statistics.
+     */
+    async getStats() {
+        const index = await this.readIndex();
+        let storageSizeBytes = 0;
+        if (existsSync(this.eventsPath)) {
+            const fileStat = await stat(this.eventsPath);
+            storageSizeBytes = fileStat.size;
+        }
+        if (existsSync(this.indexPath)) {
+            const indexStat = await stat(this.indexPath);
+            storageSizeBytes += indexStat.size;
+        }
+        return {
+            eventCount: index.eventCount,
+            storageSizeBytes,
+            oldestEvent: index.oldestTimestamp,
+            newestEvent: index.newestTimestamp,
+        };
+    }
+    /**
+     * Acquire a file-based lock for concurrent access prevention.
+     * Throws if the lock is already held by another process.
+     */
+    async acquireLock() {
+        await this.ensureDirectory();
+        // Check for stale locks
+        if (existsSync(this.lockPath)) {
+            try {
+                const lockContent = await readFile(this.lockPath, 'utf-8');
+                const lockData = JSON.parse(lockContent);
+                const age = Date.now() - lockData.timestamp;
+                if (age < LOCK_STALE_MS) {
+                    throw new Error(`Storage is locked by another process (holder: ${lockData.holder}, age: ${age}ms). ` +
+                        `Lock file: ${this.lockPath}`);
+                }
+                // Stale lock, remove it
+                await unlink(this.lockPath);
+            }
+            catch (err) {
+                if (err instanceof Error && err.message.startsWith('Storage is locked')) {
+                    throw err;
+                }
+                // Corrupted lock file, remove it
+                try {
+                    await unlink(this.lockPath);
+                }
+                catch { /* ignore */ }
+            }
+        }
+        const holder = randomUUID();
+        const lockData = { holder, timestamp: Date.now(), pid: process.pid };
+        await writeFile(this.lockPath, JSON.stringify(lockData), 'utf-8');
+        this.lockHolder = holder;
+    }
+    /**
+     * Release the file-based lock.
+     */
+    async releaseLock() {
+        if (existsSync(this.lockPath)) {
+            try {
+                const lockContent = await readFile(this.lockPath, 'utf-8');
+                const lockData = JSON.parse(lockContent);
+                // Only release if we own the lock
+                if (this.lockHolder && lockData.holder === this.lockHolder) {
+                    await unlink(this.lockPath);
+                }
+            }
+            catch {
+                // Best-effort removal
+                try {
+                    await unlink(this.lockPath);
+                }
+                catch { /* ignore */ }
+            }
+        }
+        this.lockHolder = null;
+    }
+    /**
+     * Remove all storage files (events, index, lock).
+     */
+    async destroy() {
+        for (const filePath of [this.eventsPath, this.indexPath, this.lockPath]) {
+            if (existsSync(filePath)) {
+                try {
+                    await unlink(filePath);
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    // ===== Private helpers =====
+    /**
+     * Ensure the storage directory exists.
+     */
+    async ensureDirectory() {
+        if (!existsSync(this.baseDir)) {
+            await mkdir(this.baseDir, { recursive: true });
+        }
+    }
+    /**
+     * Parse an NDJSON string into RunEvent array, skipping blank/invalid lines.
+     */
+    parseNdjson(content) {
+        const events = [];
+        const lines = content.split('\n');
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0)
+                continue;
+            try {
+                events.push(JSON.parse(trimmed));
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        return events;
+    }
+    /**
+     * Read the index file, returning a default if it does not exist.
+     */
+    async readIndex() {
+        if (!existsSync(this.indexPath)) {
+            return { eventCount: 0, oldestTimestamp: null, newestTimestamp: null, taskIds: [] };
+        }
+        try {
+            const content = await readFile(this.indexPath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return { eventCount: 0, oldestTimestamp: null, newestTimestamp: null, taskIds: [] };
+        }
+    }
+    /**
+     * Update the index with a new event.
+     */
+    async updateIndex(event) {
+        const index = await this.readIndex();
+        index.eventCount++;
+        if (index.oldestTimestamp === null || event.timestamp < index.oldestTimestamp) {
+            index.oldestTimestamp = event.timestamp;
+        }
+        if (index.newestTimestamp === null || event.timestamp > index.newestTimestamp) {
+            index.newestTimestamp = event.timestamp;
+        }
+        if (!index.taskIds.includes(event.taskId)) {
+            index.taskIds.push(event.taskId);
+        }
+        await writeFile(this.indexPath, JSON.stringify(index, null, 2), 'utf-8');
+    }
+    /**
+     * Rebuild the index from a given set of events.
+     */
+    async rebuildIndex(events) {
+        const taskIdSet = new Set();
+        let oldest = null;
+        let newest = null;
+        for (const event of events) {
+            taskIdSet.add(event.taskId);
+            if (oldest === null || event.timestamp < oldest) {
+                oldest = event.timestamp;
+            }
+            if (newest === null || event.timestamp > newest) {
+                newest = event.timestamp;
+            }
+        }
+        const index = {
+            eventCount: events.length,
+            oldestTimestamp: oldest,
+            newestTimestamp: newest,
+            taskIds: Array.from(taskIdSet),
+        };
+        await this.ensureDirectory();
+        await writeFile(this.indexPath, JSON.stringify(index, null, 2), 'utf-8');
+    }
+}
+// ============================================================================
+// PersistentLedger
+// ============================================================================
+/**
+ * A RunLedger subclass that persists events to NDJSON file storage.
+ *
+ * Extends the in-memory RunLedger with:
+ * - Automatic persistence on logEvent()
+ * - Load from storage on init via importEvents()
+ * - Explicit save()/load() for bulk operations
+ * - Compaction to enforce maxEvents limit
+ * - Storage statistics
+ * - Automatic periodic compaction via interval timer
+ */
+export class PersistentLedger extends RunLedger {
+    config;
+    store;
+    compactTimer = null;
+    initialized = false;
+    constructor(config) {
+        super();
+        this.config = { ...DEFAULT_PERSISTENCE_CONFIG, ...config };
+        this.store = new EventStore(this.config.storagePath);
+    }
+    /**
+     * Initialize the persistent ledger: load existing events from storage
+     * and start the compaction timer.
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        await this.load();
+        this.startCompactTimer();
+        this.initialized = true;
+    }
+    /**
+     * Override logEvent to also persist the event to storage.
+     */
+    logEvent(event) {
+        const logged = super.logEvent(event);
+        // Fire-and-forget persist. If enableWAL is true, we await in a microtask
+        // to minimize the chance of data loss without blocking the caller.
+        if (this.config.enableWAL) {
+            // Use a void promise to avoid unhandled rejection
+            void this.store.append(logged).catch(() => {
+                // Silently swallow persistence errors to not break the caller.
+                // In production you would log this.
+            });
+        }
+        return logged;
+    }
+    /**
+     * Override importEvents to also persist imported events to storage.
+     */
+    importEvents(events) {
+        super.importEvents(events);
+        // Persist each imported event
+        void (async () => {
+            for (const event of events) {
+                try {
+                    await this.store.append(event);
+                }
+                catch {
+                    // Silently continue
+                }
+            }
+        })();
+    }
+    /**
+     * Flush all in-memory events to storage, replacing the storage contents.
+     * This performs a full atomic rewrite of the NDJSON file.
+     */
+    async save() {
+        const events = this.exportEvents();
+        await this.store.acquireLock();
+        try {
+            await this.store.writeAll(events);
+        }
+        finally {
+            await this.store.releaseLock();
+        }
+    }
+    /**
+     * Restore events from storage into memory.
+     * Clears the in-memory ledger first, then loads all stored events.
+     */
+    async load() {
+        const events = await this.store.readAll();
+        this.clear();
+        if (events.length > 0) {
+            super.importEvents(events);
+        }
+    }
+    /**
+     * Compact the storage to keep at most maxEvents events.
+     * Also updates the in-memory ledger to match.
+     *
+     * @returns The number of evicted events.
+     */
+    async compact() {
+        await this.store.acquireLock();
+        try {
+            const evicted = await this.store.compact(this.config.maxEvents);
+            if (evicted > 0) {
+                // Reload in-memory state from the compacted storage
+                const events = await this.store.readAll();
+                this.clear();
+                if (events.length > 0) {
+                    super.importEvents(events);
+                }
+            }
+            return evicted;
+        }
+        finally {
+            await this.store.releaseLock();
+        }
+    }
+    /**
+     * Get storage statistics.
+     */
+    async getStorageStats() {
+        return this.store.getStats();
+    }
+    /**
+     * Clean up resources (stop compaction timer, release locks, etc.).
+     */
+    async destroy() {
+        this.stopCompactTimer();
+        await this.store.releaseLock();
+    }
+    /**
+     * Get the underlying EventStore (for advanced use / testing).
+     */
+    getEventStore() {
+        return this.store;
+    }
+    // ===== Private =====
+    startCompactTimer() {
+        if (this.config.compactIntervalMs > 0) {
+            this.compactTimer = setInterval(() => {
+                void this.compact().catch(() => { });
+            }, this.config.compactIntervalMs);
+            // Unref the timer so it doesn't keep the process alive
+            if (this.compactTimer && typeof this.compactTimer === 'object' && 'unref' in this.compactTimer) {
+                this.compactTimer.unref();
+            }
+        }
+    }
+    stopCompactTimer() {
+        if (this.compactTimer !== null) {
+            clearInterval(this.compactTimer);
+            this.compactTimer = null;
+        }
+    }
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Create a PersistentLedger instance. Call `init()` after creation to load
+ * existing events from storage.
+ */
+export function createPersistentLedger(config) {
+    return new PersistentLedger(config);
+}
+/**
+ * Create an EventStore instance for direct low-level storage access.
+ */
+export function createEventStore(path) {
+    return new EventStore(path);
+}
+//# sourceMappingURL=persistence.js.map

package/v3/@claude-flow/guidance/dist/proof.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Proof Envelope - Cryptographic Evidence Trail
+ *
+ * Makes every run auditable and tamper-evident by producing a hash-chained,
+ * HMAC-signed envelope for each RunEvent. Each envelope captures:
+ *
+ * - SHA-256 content hash of the run event
+ * - Hash chain linking to the previous envelope (genesis = '0' x 64)
+ * - Individual tool call hashes
+ * - Memory lineage (reads/writes with value hashes)
+ * - HMAC-SHA256 signature over the entire envelope body
+ *
+ * @module @claude-flow/guidance/proof
+ */
+import type { RunEvent } from './types.js';
+/**
+ * Record of a single tool invocation with its parameters and result.
+ */
+export interface ToolCallRecord {
+    /** Unique call identifier */
+    callId: string;
+    /** Name of the tool invoked */
+    toolName: string;
+    /** Parameters passed to the tool */
+    params: Record<string, unknown>;
+    /** Result returned by the tool */
+    result: unknown;
+    /** Timestamp of the call (epoch ms) */
+    timestamp: number;
+    /** Duration of the call in milliseconds */
+    durationMs: number;
+}
+/**
+ * Record of a memory read, write, or delete operation.
+ */
+export interface MemoryOperation {
+    /** Memory key */
+    key: string;
+    /** Memory namespace */
+    namespace: string;
+    /** Type of operation */
+    operation: 'read' | 'write' | 'delete';
+    /** SHA-256 hash of the value */
+    valueHash: string;
+    /** Timestamp of the operation (epoch ms) */
+    timestamp: number;
+}
+/**
+ * Entry in the memory lineage array stored inside a ProofEnvelope.
+ */
+export interface MemoryLineageEntry {
+    key: string;
+    namespace: string;
+    operation: 'read' | 'write' | 'delete';
+    hash: string;
+}
+/**
+ * Metadata attached to every proof envelope.
+ */
+export interface ProofEnvelopeMetadata {
+    agentId: string;
+    sessionId: string;
+    parentEnvelopeId?: string;
+}
+/**
+ * A cryptographically signed, hash-chained proof envelope.
+ */
+export interface ProofEnvelope {
+    /** Unique envelope identifier */
+    envelopeId: string;
+    /** Reference to the RunEvent this envelope covers */
+    runEventId: string;
+    /** ISO 8601 timestamp of envelope creation */
+    timestamp: string;
+    /** SHA-256 hash of the full RunEvent */
+    contentHash: string;
+    /** Hash of the previous envelope in the chain (genesis = '0'.repeat(64)) */
+    previousHash: string;
+    /** Map of tool call ID to SHA-256(toolName + params + result) */
+    toolCallHashes: Record<string, string>;
+    /** SHA-256 hash of the policy bundle used */
+    guidanceHash: string;
+    /** Lineage of memory operations during the run */
+    memoryLineage: MemoryLineageEntry[];
+    /** HMAC-SHA256 signature of the envelope content */
+    signature: string;
+    /** Contextual metadata */
+    metadata: ProofEnvelopeMetadata;
+}
+/**
+ * Serializable chain representation for export/import.
+ */
+export interface SerializedProofChain {
+    envelopes: ProofEnvelope[];
+    createdAt: string;
+    version: number;
+}
+/**
+ * A tamper-evident, hash-chained sequence of ProofEnvelopes.
+ *
+ * Each envelope links to the previous one via `previousHash`, forming
+ * a blockchain-like structure. Every envelope is HMAC-signed so any
+ * modification to the chain can be detected.
+ */
+export declare class ProofChain {
+    private envelopes;
+    private readonly signingKey;
+    constructor(signingKey: string);
+    /**
+     * Append a new ProofEnvelope to the chain.
+     *
+     * @param runEvent - The RunEvent to wrap
+     * @param toolCalls - Tool call records from the run
+     * @param memoryOps - Memory operations from the run
+     * @param metadata - Optional metadata overrides
+     * @returns The newly created and signed ProofEnvelope
+     */
+    append(runEvent: RunEvent, toolCalls?: ToolCallRecord[], memoryOps?: MemoryOperation[], metadata?: Partial<ProofEnvelopeMetadata>): ProofEnvelope;
+    /**
+     * Verify a single envelope's HMAC signature and hash chain link.
+     *
+     * @returns true if the signature is valid and the previousHash is correct
+     */
+    verify(envelope: ProofEnvelope): boolean;
+    /**
+     * Verify the entire chain from genesis to tip.
+     *
+     * Checks that every envelope:
+     * 1. Has a valid HMAC signature
+     * 2. Links correctly to the previous envelope's contentHash
+     *
+     * @returns true if the full chain is intact
+     */
+    verifyChain(): boolean;
+    /**
+     * Retrieve an envelope by its ID.
+     */
+    getEnvelope(id: string): ProofEnvelope | undefined;
+    /**
+     * Get the most recent envelope in the chain.
+     */
+    getChainTip(): ProofEnvelope | undefined;
+    /**
+     * Get the number of envelopes in the chain.
+     */
+    getChainLength(): number;
+    /**
+     * Export the chain as a serializable object.
+     */
+    export(): SerializedProofChain;
+    /**
+     * Restore the chain from a previously exported object.
+     *
+     * Replaces the current chain contents entirely.
+     */
+    import(data: SerializedProofChain): void;
+    /**
+     * Compute the SHA-256 content hash of a RunEvent.
+     */
+    private computeContentHash;
+    /**
+     * Compute the SHA-256 hash of a single tool call.
+     *
+     * Hash = SHA-256(toolName + JSON(params) + JSON(result))
+     */
+    private computeToolCallHash;
+    /**
+     * Produce the HMAC-SHA256 signature for an envelope.
+     *
+     * The signature covers every field except `signature` itself.
+     */
+    private signEnvelope;
+}
+/**
+ * Create a new ProofChain instance.
+ *
+ * @param config - Configuration with a required `signingKey` for HMAC signing.
+ *   Callers that previously relied on the optional signature must now provide
+ *   an explicit key (see ADR-G026).
+ * @returns A fresh ProofChain
+ */
+export declare function createProofChain(config: {
+    signingKey: string;
+}): ProofChain;
+//# sourceMappingURL=proof.d.ts.map