claude-flow 3.27.4 → 3.29.0

package/v3/@claude-flow/shared/dist/events/rvf-event-log.js

@@ -0,0 +1,340 @@
+/**
+ * RVF Event Log (ADR-057 Phase 2)
+ *
+ * Pure-TypeScript append-only event log that stores events in a binary
+ * file format. Replaces the sql.js-dependent EventStore with a zero-
+ * dependency alternative.
+ *
+ * Binary format:
+ *   File header:  4 bytes — magic "RVFL"
+ *   Record:       4 bytes (uint32 BE payload length) + N bytes (JSON payload)
+ *
+ * In-memory indexes are rebuilt on initialize() by replaying the file.
+ * Snapshots are stored in a separate `.snap.rvf` file using the same format.
+ *
+ * @module v3/shared/events/rvf-event-log
+ */
+import { EventEmitter } from 'node:events';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** Validate a file path is safe */
+function validatePath(p) {
+    if (p.includes('\0'))
+        throw new Error('Event log path contains null bytes');
+}
+const DEFAULT_CONFIG = {
+    logPath: 'events.rvf',
+    verbose: false,
+    snapshotThreshold: 100,
+};
+// =============================================================================
+// Constants
+// =============================================================================
+/** Magic bytes that identify an RVF event log file */
+const MAGIC = Buffer.from('RVFL');
+const MAGIC_LENGTH = 4;
+const LENGTH_PREFIX_BYTES = 4;
+// =============================================================================
+// RvfEventLog Implementation
+// =============================================================================
+export class RvfEventLog extends EventEmitter {
+    config;
+    initialized = false;
+    /**
+     * All events kept in insertion order.
+     * Rebuilt from the file on initialize().
+     */
+    events = [];
+    /** Fast lookup: aggregateId -> indices into this.events */
+    aggregateIndex = new Map();
+    /** Version tracking per aggregate */
+    aggregateVersions = new Map();
+    /** Snapshots keyed by aggregateId (latest wins) */
+    snapshots = new Map();
+    /** Path to the companion snapshot file */
+    snapshotPath;
+    constructor(config = {}) {
+        super();
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.snapshotPath = this.config.logPath.replace(/\.rvf$/, '.snap.rvf');
+        if (this.snapshotPath === this.config.logPath) {
+            this.snapshotPath = this.config.logPath + '.snap.rvf';
+        }
+        validatePath(this.config.logPath);
+    }
+    // ===========================================================================
+    // Lifecycle
+    // ===========================================================================
+    /** Create / open the log file and rebuild in-memory indexes. */
+    async initialize() {
+        if (this.initialized)
+            return;
+        this.ensureDirectory(this.config.logPath);
+        // --- events file ---
+        if (existsSync(this.config.logPath)) {
+            this.replayFile(this.config.logPath, (event) => {
+                this.indexEvent(event);
+            });
+        }
+        else {
+            const tmpLog = this.config.logPath + '.tmp';
+            writeFileSync(tmpLog, MAGIC);
+            renameSync(tmpLog, this.config.logPath);
+        }
+        // --- snapshots file ---
+        if (existsSync(this.snapshotPath)) {
+            this.replayFile(this.snapshotPath, (_raw) => {
+                const snap = _raw;
+                this.snapshots.set(snap.aggregateId, snap);
+            });
+        }
+        else {
+            const tmpSnap = this.snapshotPath + '.tmp';
+            writeFileSync(tmpSnap, MAGIC);
+            renameSync(tmpSnap, this.snapshotPath);
+        }
+        this.initialized = true;
+        if (this.config.verbose) {
+            console.log(`[RvfEventLog] Initialized – ${this.events.length} events, ` +
+                `${this.snapshots.size} snapshots`);
+        }
+        this.emit('initialized');
+    }
+    /** Flush to disk and release resources. */
+    async close() {
+        if (!this.initialized)
+            return;
+        // All data is already on disk (append-only), so just clear memory.
+        this.events = [];
+        this.aggregateIndex.clear();
+        this.aggregateVersions.clear();
+        this.snapshots.clear();
+        this.initialized = false;
+        this.emit('shutdown');
+    }
+    // ===========================================================================
+    // Write Operations
+    // ===========================================================================
+    /** Append a domain event to the log. */
+    async append(event) {
+        this.ensureInitialized();
+        if (!event.aggregateId || typeof event.aggregateId !== 'string') {
+            throw new Error('Event must have a valid aggregateId string');
+        }
+        if (!event.type || typeof event.type !== 'string') {
+            throw new Error('Event must have a valid type string');
+        }
+        // Assign next version for aggregate
+        const currentVersion = this.aggregateVersions.get(event.aggregateId) ?? 0;
+        const nextVersion = currentVersion + 1;
+        event.version = nextVersion;
+        // Persist to disk first (crash-safe ordering)
+        this.appendRecord(this.config.logPath, event);
+        // Update in-memory state
+        this.indexEvent(event);
+        this.emit('event:appended', event);
+        if (nextVersion % this.config.snapshotThreshold === 0) {
+            this.emit('snapshot:recommended', {
+                aggregateId: event.aggregateId,
+                version: nextVersion,
+            });
+        }
+    }
+    /** Save a snapshot for an aggregate. */
+    async saveSnapshot(snapshot) {
+        this.ensureInitialized();
+        this.appendRecord(this.snapshotPath, snapshot);
+        this.snapshots.set(snapshot.aggregateId, snapshot);
+        this.emit('snapshot:saved', snapshot);
+    }
+    // ===========================================================================
+    // Read Operations
+    // ===========================================================================
+    /** Get events for a specific aggregate, optionally from a version. */
+    async getEvents(aggregateId, fromVersion) {
+        this.ensureInitialized();
+        const indices = this.aggregateIndex.get(aggregateId);
+        if (!indices || indices.length === 0)
+            return [];
+        let result = indices.map((i) => this.events[i]);
+        if (fromVersion !== undefined) {
+            result = result.filter((e) => e.version >= fromVersion);
+        }
+        // Events within an aggregate are already version-ordered because we
+        // append in order, but sort defensively.
+        return result.sort((a, b) => a.version - b.version);
+    }
+    /** Query events with an optional filter (matches EventStore.query API). */
+    async getAllEvents(filter) {
+        this.ensureInitialized();
+        if (!filter) {
+            return [...this.events].sort((a, b) => a.timestamp - b.timestamp);
+        }
+        let result = [...this.events];
+        // Aggregate ID filter
+        if (filter.aggregateIds && filter.aggregateIds.length > 0) {
+            const set = new Set(filter.aggregateIds);
+            result = result.filter((e) => set.has(e.aggregateId));
+        }
+        // Aggregate type filter
+        if (filter.aggregateTypes && filter.aggregateTypes.length > 0) {
+            const set = new Set(filter.aggregateTypes);
+            result = result.filter((e) => set.has(e.aggregateType));
+        }
+        // Event type filter
+        if (filter.eventTypes && filter.eventTypes.length > 0) {
+            const set = new Set(filter.eventTypes);
+            result = result.filter((e) => set.has(e.type));
+        }
+        // Timestamp filters
+        if (filter.afterTimestamp !== undefined) {
+            result = result.filter((e) => e.timestamp > filter.afterTimestamp);
+        }
+        if (filter.beforeTimestamp !== undefined) {
+            result = result.filter((e) => e.timestamp < filter.beforeTimestamp);
+        }
+        // Version filter
+        if (filter.fromVersion !== undefined) {
+            result = result.filter((e) => e.version >= filter.fromVersion);
+        }
+        // Sort by timestamp ascending (matches EventStore behaviour)
+        result.sort((a, b) => a.timestamp - b.timestamp);
+        // Pagination
+        if (filter.offset) {
+            result = result.slice(filter.offset);
+        }
+        if (filter.limit) {
+            result = result.slice(0, filter.limit);
+        }
+        return result;
+    }
+    /** Get latest snapshot for an aggregate. */
+    async getSnapshot(aggregateId) {
+        this.ensureInitialized();
+        return this.snapshots.get(aggregateId) ?? null;
+    }
+    /** Return event store statistics. */
+    async getStats() {
+        this.ensureInitialized();
+        const eventsByType = {};
+        const eventsByAggregate = {};
+        let oldest = null;
+        let newest = null;
+        for (const event of this.events) {
+            // by type
+            eventsByType[event.type] = (eventsByType[event.type] ?? 0) + 1;
+            // by aggregate
+            eventsByAggregate[event.aggregateId] =
+                (eventsByAggregate[event.aggregateId] ?? 0) + 1;
+            // timestamp range
+            if (oldest === null || event.timestamp < oldest)
+                oldest = event.timestamp;
+            if (newest === null || event.timestamp > newest)
+                newest = event.timestamp;
+        }
+        return {
+            totalEvents: this.events.length,
+            eventsByType,
+            eventsByAggregate,
+            oldestEvent: oldest,
+            newestEvent: newest,
+            snapshotCount: this.snapshots.size,
+        };
+    }
+    /**
+     * Flush to disk.
+     * For the append-only log this is a no-op because every append() call
+     * writes to disk synchronously. Provided for API compatibility with
+     * EventStore.
+     */
+    async persist() {
+        // All records are already flushed on append. Nothing to do.
+        if (this.config.verbose) {
+            console.log('[RvfEventLog] persist() called — all data already on disk');
+        }
+    }
+    // ===========================================================================
+    // Private Helpers
+    // ===========================================================================
+    /**
+     * Replay an RVF file and invoke `handler` for every decoded record.
+     * Used both for events and snapshots.
+     */
+    replayFile(filePath, handler) {
+        const buf = readFileSync(filePath);
+        // Validate magic
+        if (buf.length < MAGIC_LENGTH || buf.subarray(0, MAGIC_LENGTH).compare(MAGIC) !== 0) {
+            throw new Error(`[RvfEventLog] Invalid file header in ${filePath}`);
+        }
+        let offset = MAGIC_LENGTH;
+        const MAX_PAYLOAD_SIZE = 100 * 1024 * 1024; // 100MB safety limit
+        while (offset + LENGTH_PREFIX_BYTES <= buf.length) {
+            const payloadLength = buf.readUInt32BE(offset);
+            offset += LENGTH_PREFIX_BYTES;
+            if (payloadLength > MAX_PAYLOAD_SIZE) {
+                if (this.config.verbose) {
+                    console.warn(`[RvfEventLog] Payload size ${payloadLength} exceeds safety limit`);
+                }
+                break;
+            }
+            if (offset + payloadLength > buf.length) {
+                // Truncated record — stop reading (crash recovery).
+                if (this.config.verbose) {
+                    console.warn(`[RvfEventLog] Truncated record at offset ${offset - LENGTH_PREFIX_BYTES} — ` +
+                        `expected ${payloadLength} bytes, have ${buf.length - offset}`);
+                }
+                break;
+            }
+            const json = buf.subarray(offset, offset + payloadLength).toString('utf8');
+            offset += payloadLength;
+            try {
+                const record = JSON.parse(json);
+                handler(record);
+            }
+            catch {
+                if (this.config.verbose) {
+                    console.warn(`[RvfEventLog] Corrupt JSON record skipped`);
+                }
+            }
+        }
+    }
+    /** Append a single record to an RVF file. */
+    appendRecord(filePath, record) {
+        const json = JSON.stringify(record);
+        const payload = Buffer.from(json, 'utf8');
+        const lengthBuf = Buffer.allocUnsafe(LENGTH_PREFIX_BYTES);
+        lengthBuf.writeUInt32BE(payload.length, 0);
+        appendFileSync(filePath, Buffer.concat([lengthBuf, payload]));
+    }
+    /** Add an event to the in-memory indexes. */
+    indexEvent(event) {
+        const idx = this.events.length;
+        this.events.push(event);
+        // aggregateIndex
+        let indices = this.aggregateIndex.get(event.aggregateId);
+        if (!indices) {
+            indices = [];
+            this.aggregateIndex.set(event.aggregateId, indices);
+        }
+        indices.push(idx);
+        // version tracker
+        const current = this.aggregateVersions.get(event.aggregateId) ?? 0;
+        if (event.version > current) {
+            this.aggregateVersions.set(event.aggregateId, event.version);
+        }
+    }
+    /** Ensure parent directory exists for a file path. */
+    ensureDirectory(filePath) {
+        const dir = dirname(filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+    /** Guard that throws if initialize() has not been called. */
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error('RvfEventLog not initialized. Call initialize() first.');
+        }
+    }
+}
+//# sourceMappingURL=rvf-event-log.js.map

package/v3/@claude-flow/shared/dist/events/state-reconstructor.d.ts

@@ -0,0 +1,101 @@
+/**
+ * State Reconstructor - ADR-007 Implementation
+ *
+ * Reconstructs aggregate state from event streams.
+ * Implements event sourcing patterns for V3.
+ *
+ * @module v3/shared/events/state-reconstructor
+ */
+import { EventStore } from './event-store.js';
+import type { DomainEvent } from './domain-events.js';
+/**
+ * Aggregate root interface
+ */
+export interface AggregateRoot {
+    id: string;
+    version: number;
+    apply(event: DomainEvent): void;
+    getState(): Record<string, unknown>;
+}
+/**
+ * Reconstructor options
+ */
+export interface ReconstructorOptions {
+    useSnapshots: boolean;
+    snapshotInterval: number;
+    maxEventsToReplay: number;
+}
+/**
+ * State Reconstructor
+ *
+ * Reconstructs aggregate state from event history.
+ * Supports snapshots for performance optimization.
+ */
+export declare class StateReconstructor {
+    private readonly eventStore;
+    private readonly options;
+    constructor(eventStore: EventStore, options?: Partial<ReconstructorOptions>);
+    /**
+     * Reconstruct aggregate state from events
+     */
+    reconstruct<T extends AggregateRoot>(aggregateId: string, factory: (id: string) => T): Promise<T>;
+    /**
+     * Reconstruct state at a specific point in time
+     */
+    reconstructAtTime<T extends AggregateRoot>(aggregateId: string, factory: (id: string) => T, timestamp: Date): Promise<T>;
+    /**
+     * Reconstruct state at a specific version
+     */
+    reconstructAtVersion<T extends AggregateRoot>(aggregateId: string, factory: (id: string) => T, targetVersion: number): Promise<T>;
+    /**
+     * Apply snapshot to aggregate
+     */
+    private applySnapshot;
+    /**
+     * Create snapshot for aggregate
+     */
+    private createSnapshot;
+    /**
+     * Get aggregate type from instance
+     */
+    private getAggregateType;
+}
+/**
+ * Agent Aggregate - Example implementation
+ */
+export declare class AgentAggregate implements AggregateRoot {
+    id: string;
+    version: number;
+    private state;
+    constructor(id: string);
+    apply(event: DomainEvent): void;
+    getState(): Record<string, unknown>;
+    restoreFromSnapshot(snapshotState: unknown): void;
+    get name(): string;
+    get role(): string;
+    get status(): string;
+    get currentTask(): string | null;
+    get completedTasks(): string[];
+    get capabilities(): string[];
+}
+/**
+ * Task Aggregate - Example implementation
+ */
+export declare class TaskAggregate implements AggregateRoot {
+    id: string;
+    version: number;
+    private state;
+    constructor(id: string);
+    apply(event: DomainEvent): void;
+    getState(): Record<string, unknown>;
+    restoreFromSnapshot(snapshotState: unknown): void;
+    get title(): string;
+    get status(): string;
+    get assignedAgent(): string | null;
+    get result(): unknown;
+}
+/**
+ * Factory function
+ */
+export declare function createStateReconstructor(eventStore: EventStore, options?: Partial<ReconstructorOptions>): StateReconstructor;
+//# sourceMappingURL=state-reconstructor.d.ts.map

package/v3/@claude-flow/shared/dist/events/state-reconstructor.js

@@ -0,0 +1,263 @@
+/**
+ * State Reconstructor - ADR-007 Implementation
+ *
+ * Reconstructs aggregate state from event streams.
+ * Implements event sourcing patterns for V3.
+ *
+ * @module v3/shared/events/state-reconstructor
+ */
+/**
+ * State Reconstructor
+ *
+ * Reconstructs aggregate state from event history.
+ * Supports snapshots for performance optimization.
+ */
+export class StateReconstructor {
+    eventStore;
+    options;
+    constructor(eventStore, options) {
+        this.eventStore = eventStore;
+        this.options = {
+            useSnapshots: true,
+            snapshotInterval: 100,
+            maxEventsToReplay: 10000,
+            ...options,
+        };
+    }
+    /**
+     * Reconstruct aggregate state from events
+     */
+    async reconstruct(aggregateId, factory) {
+        const aggregate = factory(aggregateId);
+        // Try to load from snapshot first
+        if (this.options.useSnapshots) {
+            const snapshot = await this.eventStore.getSnapshot(aggregateId);
+            if (snapshot) {
+                this.applySnapshot(aggregate, snapshot);
+            }
+        }
+        // Get events after snapshot version (or all if no snapshot)
+        const events = await this.eventStore.getEvents(aggregateId, aggregate.version + 1);
+        // Apply events
+        for (const event of events) {
+            if (events.length > this.options.maxEventsToReplay) {
+                throw new Error(`Too many events to replay (${events.length}). Consider creating a snapshot.`);
+            }
+            aggregate.apply(event);
+        }
+        // Create snapshot if interval reached
+        if (this.options.useSnapshots && aggregate.version % this.options.snapshotInterval === 0) {
+            await this.createSnapshot(aggregate);
+        }
+        return aggregate;
+    }
+    /**
+     * Reconstruct state at a specific point in time
+     */
+    async reconstructAtTime(aggregateId, factory, timestamp) {
+        const aggregate = factory(aggregateId);
+        // Get all events up to timestamp
+        const allEvents = await this.eventStore.getEvents(aggregateId);
+        const events = allEvents.filter((e) => e.timestamp <= timestamp.getTime());
+        // Apply events
+        for (const event of events) {
+            aggregate.apply(event);
+        }
+        return aggregate;
+    }
+    /**
+     * Reconstruct state at a specific version
+     */
+    async reconstructAtVersion(aggregateId, factory, targetVersion) {
+        const aggregate = factory(aggregateId);
+        // Get events up to target version
+        const events = await this.eventStore.getEvents(aggregateId);
+        const limitedEvents = events.filter((e) => e.version <= targetVersion);
+        // Apply events
+        for (const event of limitedEvents) {
+            aggregate.apply(event);
+        }
+        return aggregate;
+    }
+    /**
+     * Apply snapshot to aggregate
+     */
+    applySnapshot(aggregate, snapshot) {
+        // Type assertion for aggregate that has restoreFromSnapshot
+        const restorable = aggregate;
+        if (typeof restorable.restoreFromSnapshot === 'function') {
+            restorable.restoreFromSnapshot(snapshot.state);
+        }
+        // Update version
+        aggregate.version = snapshot.version;
+    }
+    /**
+     * Create snapshot for aggregate
+     */
+    async createSnapshot(aggregate) {
+        const snapshot = {
+            aggregateId: aggregate.id,
+            aggregateType: this.getAggregateType(aggregate),
+            version: aggregate.version,
+            state: aggregate.getState(),
+            timestamp: Date.now(),
+        };
+        await this.eventStore.saveSnapshot(snapshot);
+    }
+    /**
+     * Get aggregate type from instance
+     */
+    getAggregateType(aggregate) {
+        const typeName = aggregate.constructor.name.toLowerCase().replace('aggregate', '');
+        // Map to valid aggregate types
+        if (typeName === 'agent' || typeName === 'task' || typeName === 'memory' || typeName === 'swarm') {
+            return typeName;
+        }
+        return 'agent'; // Default fallback
+    }
+}
+/**
+ * Agent Aggregate - Example implementation
+ */
+export class AgentAggregate {
+    id;
+    version = 0;
+    state = {
+        name: '',
+        role: '',
+        status: 'idle',
+        currentTask: null,
+        completedTasks: [],
+        capabilities: [],
+        createdAt: null,
+        lastActiveAt: null,
+    };
+    constructor(id) {
+        this.id = id;
+    }
+    apply(event) {
+        this.version = event.version;
+        switch (event.type) {
+            case 'agent:spawned':
+                this.state.name = event.payload.name;
+                this.state.role = event.payload.role;
+                this.state.capabilities = event.payload.capabilities ?? [];
+                this.state.status = 'idle';
+                this.state.createdAt = new Date(event.timestamp);
+                break;
+            case 'agent:started':
+                this.state.status = 'active';
+                this.state.lastActiveAt = new Date(event.timestamp);
+                break;
+            case 'agent:task-assigned':
+                this.state.currentTask = event.payload.taskId;
+                this.state.status = 'busy';
+                this.state.lastActiveAt = new Date(event.timestamp);
+                break;
+            case 'agent:task-completed':
+                this.state.completedTasks.push(event.payload.taskId);
+                this.state.currentTask = null;
+                this.state.status = 'active';
+                this.state.lastActiveAt = new Date(event.timestamp);
+                break;
+            case 'agent:terminated':
+                this.state.status = 'terminated';
+                break;
+        }
+    }
+    getState() {
+        return { ...this.state };
+    }
+    restoreFromSnapshot(snapshotState) {
+        const state = snapshotState;
+        this.state = {
+            ...state,
+            createdAt: state.createdAt ? new Date(state.createdAt) : null,
+            lastActiveAt: state.lastActiveAt ? new Date(state.lastActiveAt) : null,
+        };
+    }
+    // Getters for type safety
+    get name() { return this.state.name; }
+    get role() { return this.state.role; }
+    get status() { return this.state.status; }
+    get currentTask() { return this.state.currentTask; }
+    get completedTasks() { return [...this.state.completedTasks]; }
+    get capabilities() { return [...this.state.capabilities]; }
+}
+/**
+ * Task Aggregate - Example implementation
+ */
+export class TaskAggregate {
+    id;
+    version = 0;
+    state = {
+        title: '',
+        description: '',
+        type: '',
+        priority: 'normal',
+        status: 'pending',
+        assignedAgent: null,
+        result: null,
+        createdAt: null,
+        startedAt: null,
+        completedAt: null,
+    };
+    constructor(id) {
+        this.id = id;
+    }
+    apply(event) {
+        this.version = event.version;
+        switch (event.type) {
+            case 'task:created':
+                this.state.title = event.payload.title;
+                this.state.description = event.payload.description;
+                this.state.type = event.payload.taskType;
+                this.state.priority = event.payload.priority ?? 'normal';
+                this.state.status = 'pending';
+                this.state.createdAt = new Date(event.timestamp);
+                break;
+            case 'task:started':
+                this.state.assignedAgent = event.payload.agentId;
+                this.state.status = 'running';
+                this.state.startedAt = new Date(event.timestamp);
+                break;
+            case 'task:completed':
+                this.state.result = event.payload.result;
+                this.state.status = 'completed';
+                this.state.completedAt = new Date(event.timestamp);
+                break;
+            case 'task:failed':
+                this.state.status = 'failed';
+                this.state.completedAt = new Date(event.timestamp);
+                break;
+            case 'task:cancelled':
+                this.state.status = 'cancelled';
+                this.state.completedAt = new Date(event.timestamp);
+                break;
+        }
+    }
+    getState() {
+        return { ...this.state };
+    }
+    restoreFromSnapshot(snapshotState) {
+        const state = snapshotState;
+        this.state = {
+            ...state,
+            createdAt: state.createdAt ? new Date(state.createdAt) : null,
+            startedAt: state.startedAt ? new Date(state.startedAt) : null,
+            completedAt: state.completedAt ? new Date(state.completedAt) : null,
+        };
+    }
+    // Getters
+    get title() { return this.state.title; }
+    get status() { return this.state.status; }
+    get assignedAgent() { return this.state.assignedAgent; }
+    get result() { return this.state.result; }
+}
+/**
+ * Factory function
+ */
+export function createStateReconstructor(eventStore, options) {
+    return new StateReconstructor(eventStore, options);
+}
+//# sourceMappingURL=state-reconstructor.js.map