@reactive-skills/runtime 0.1.0

package/dist/core/event-store.js

@@ -0,0 +1,762 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { DatabaseSync } from 'node:sqlite';
+export const EVENT_STORE_SCHEMA_VERSION = 2;
+export function createSortableId() {
+    const bytes = crypto.randomBytes(16);
+    const timestamp = BigInt(Date.now());
+    for (let index = 0; index < 6; index++) {
+        bytes[index] = Number((timestamp >> BigInt((5 - index) * 8)) & 0xffn);
+    }
+    bytes[6] = (bytes[6] & 0x0f) | 0x70;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/**
+ * SQLite Storage Driver for EventStore
+ * Provides ACID relational storage, indexing, and direct SQL querying
+ */
+export class SQLiteStorageDriver {
+    db;
+    constructor(dbPath) {
+        if (dbPath !== ':memory:') {
+            const dir = path.dirname(dbPath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+        }
+        this.db = new DatabaseSync(dbPath);
+        this.db.exec('PRAGMA busy_timeout = 5000');
+        this.db.exec('PRAGMA journal_mode = WAL');
+        this.initTables();
+    }
+    initTables() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS events (
+        id TEXT PRIMARY KEY,
+        event_id TEXT,
+        seq INTEGER NOT NULL,
+        timestamp TEXT NOT NULL,
+        occurred_at TEXT,
+        type TEXT NOT NULL,
+        event_type TEXT,
+        state TEXT,
+        source TEXT,
+        causation_id TEXT,
+        correlation_id TEXT,
+        request_id TEXT,
+        trace_parent TEXT,
+        skill_id TEXT,
+        run_id TEXT,
+        parent_run_id TEXT,
+        schema_version TEXT,
+        payload TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_events_seq ON events(seq);
+      CREATE INDEX IF NOT EXISTS idx_events_type ON events(type);
+      CREATE INDEX IF NOT EXISTS idx_events_state ON events(state);
+
+      CREATE TABLE IF NOT EXISTS projections (
+        name TEXT PRIMARY KEY,
+        content TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS state_snapshots (
+        seq INTEGER PRIMARY KEY,
+        state TEXT NOT NULL,
+        context TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS projection_watermarks (
+        name TEXT PRIMARY KEY,
+        event_seq INTEGER NOT NULL,
+        projection_version TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS schema_version (
+        version INTEGER PRIMARY KEY,
+        applied_at TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS seq_counter (
+        id INTEGER PRIMARY KEY,
+        last_seq INTEGER NOT NULL
+      );
+      INSERT OR IGNORE INTO seq_counter (id, last_seq) VALUES (1, 0);
+      INSERT OR IGNORE INTO schema_version (version, applied_at) VALUES (2, datetime('now'));
+    `);
+        this.ensureSchemaVersion();
+    }
+    ensureSchemaVersion() {
+        const stmt = this.db.prepare('SELECT MAX(version) as v FROM schema_version');
+        const row = stmt.get();
+        const currentVersion = row?.v ?? 0;
+        if (currentVersion < EVENT_STORE_SCHEMA_VERSION) {
+            this.runMigrations(currentVersion);
+        }
+    }
+    runMigrations(fromVersion) {
+        if (fromVersion < 2) {
+            const envelopeColumns = {
+                event_id: 'TEXT',
+                occurred_at: 'TEXT',
+                event_type: 'TEXT',
+                correlation_id: 'TEXT',
+                request_id: 'TEXT',
+                trace_parent: 'TEXT',
+                skill_id: 'TEXT',
+                run_id: 'TEXT',
+                parent_run_id: 'TEXT',
+                schema_version: 'TEXT',
+            };
+            for (const [column, type] of Object.entries(envelopeColumns)) {
+                try {
+                    this.db.exec(`ALTER TABLE events ADD COLUMN ${column} ${type}`);
+                }
+                catch {
+                    // Column already exists, skip
+                }
+            }
+            this.db.exec(`INSERT OR IGNORE INTO schema_version (version, applied_at) VALUES (2, datetime('now'))`);
+            console.warn('EventStore: Migrated schema from v' + fromVersion + ' to v2 (added event envelope fields)');
+        }
+    }
+    insertEvent(event) {
+        const stmt = this.db.prepare(`
+      INSERT INTO events (id, event_id, seq, timestamp, occurred_at, type, event_type, state, source, causation_id, correlation_id, request_id, trace_parent, skill_id, run_id, parent_run_id, schema_version, payload)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        stmt.run(event.id, event.event_id || event.id, event.seq, event.timestamp, event.occurred_at || event.timestamp, event.type, event.event_type || event.type, event.state || null, event.source || null, event.causation_id || event.causationId || null, event.correlation_id || null, event.request_id || null, event.trace_parent || null, event.skill_id || null, event.run_id || null, event.parent_run_id || null, event.schema_version || null, JSON.stringify(event.payload));
+    }
+    beginTransaction() {
+        this.db.exec('BEGIN IMMEDIATE');
+    }
+    commitTransaction() {
+        this.db.exec('COMMIT');
+    }
+    queryEvents(options = {}) {
+        let sql = 'SELECT * FROM events WHERE 1=1';
+        const params = [];
+        if (options.type) {
+            sql += ' AND type = ?';
+            params.push(options.type);
+        }
+        if (options.state) {
+            sql += ' AND state = ?';
+            params.push(options.state);
+        }
+        if (options.sinceSeq !== undefined) {
+            sql += ' AND seq > ?';
+            params.push(options.sinceSeq);
+        }
+        sql += ' ORDER BY seq ASC';
+        if (options.limit) {
+            sql += ' LIMIT ?';
+            params.push(options.limit);
+        }
+        const stmt = this.db.prepare(sql);
+        const rows = stmt.all(...params);
+        return rows.map(row => this.rowToEvent(row));
+    }
+    getLatestSequence() {
+        const stmt = this.db.prepare('SELECT seq FROM events ORDER BY seq DESC LIMIT 1');
+        const row = stmt.get();
+        return row ? Number(row.seq) : 0;
+    }
+    nextSequence() {
+        const stmt = this.db.prepare('UPDATE seq_counter SET last_seq = last_seq + 1 WHERE id = 1');
+        stmt.run();
+        const selectStmt = this.db.prepare('SELECT last_seq FROM seq_counter WHERE id = 1');
+        const row = selectStmt.get();
+        return Number(row.last_seq);
+    }
+    getRecentEvents(limit) {
+        const boundedLimit = Math.max(1, Math.floor(limit));
+        const stmt = this.db.prepare('SELECT * FROM events ORDER BY seq DESC LIMIT ?');
+        const rows = stmt.all(boundedLimit);
+        return rows.reverse().map(row => this.rowToEvent(row));
+    }
+    querySql(sql, params = []) {
+        const normalizedSql = sql.replace(/--.*(?:\r?\n|$)/g, '').trim();
+        const statements = normalizedSql.split(';').map(statement => statement.trim()).filter(Boolean);
+        if (statements.length !== 1 || !/^(SELECT|EXPLAIN)\b/i.test(statements[0])) {
+            throw new Error('Only single-statement SELECT or EXPLAIN queries are allowed.');
+        }
+        const stmt = this.db.prepare(sql);
+        return stmt.all(...params);
+    }
+    saveSnapshot(seq, state, context) {
+        const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO state_snapshots (seq, state, context, created_at)
+      VALUES (?, ?, ?, ?)
+    `);
+        stmt.run(seq, state, JSON.stringify(context), new Date().toISOString());
+    }
+    getLatestSnapshot() {
+        const stmt = this.db.prepare(`
+      SELECT * FROM state_snapshots ORDER BY seq DESC LIMIT 1
+    `);
+        const row = stmt.get();
+        if (!row)
+            return null;
+        return {
+            seq: Number(row.seq),
+            state: row.state,
+            context: JSON.parse(row.context),
+        };
+    }
+    saveProjectionWatermark(name, eventSeq, projectionVersion) {
+        const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO projection_watermarks (name, event_seq, projection_version, updated_at)
+      VALUES (?, ?, ?, ?)
+    `);
+        stmt.run(name, eventSeq, projectionVersion, new Date().toISOString());
+    }
+    getProjectionWatermark(name) {
+        const stmt = this.db.prepare('SELECT event_seq, projection_version FROM projection_watermarks WHERE name = ?');
+        const row = stmt.get(name);
+        return row
+            ? { eventSeq: Number(row.event_seq), projectionVersion: row.projection_version }
+            : null;
+    }
+    saveProjection(name, content) {
+        const stmt = this.db.prepare(`
+      INSERT OR REPLACE INTO projections (name, content, updated_at)
+      VALUES (?, ?, ?)
+    `);
+        stmt.run(name, content, new Date().toISOString());
+    }
+    getProjection(name) {
+        const stmt = this.db.prepare(`
+      SELECT content FROM projections WHERE name = ?
+    `);
+        const row = stmt.get(name);
+        return row ? row.content : null;
+    }
+    close() {
+        this.db.close();
+    }
+    static getSchemaVersion(dbPath) {
+        const db = new DatabaseSync(dbPath);
+        const stmt = db.prepare('SELECT MAX(version) as v FROM schema_version');
+        const row = stmt.get();
+        db.close();
+        return row?.v ?? 0;
+    }
+    rowToEvent(row) {
+        return {
+            id: row.id,
+            seq: Number(row.seq),
+            timestamp: row.timestamp,
+            type: row.type,
+            state: row.state || undefined,
+            source: row.source || undefined,
+            causationId: row.causation_id || undefined,
+            event_id: row.event_id || row.id,
+            occurred_at: row.occurred_at || row.timestamp,
+            event_type: row.event_type || row.type,
+            causation_id: row.causation_id || undefined,
+            correlation_id: row.correlation_id || undefined,
+            request_id: row.request_id || undefined,
+            trace_parent: row.trace_parent || undefined,
+            skill_id: row.skill_id || undefined,
+            run_id: row.run_id || undefined,
+            parent_run_id: row.parent_run_id || undefined,
+            schema_version: row.schema_version || undefined,
+            payload: JSON.parse(row.payload),
+        };
+    }
+    clear() {
+        this.db.exec(`
+      DELETE FROM events;
+      DELETE FROM projections;
+      DELETE FROM state_snapshots;
+      DELETE FROM projection_watermarks;
+    `);
+    }
+    /**
+     * Purge every table including seq_counter so a rebuilt store starts from a
+     * clean slate. Used by EventStore.rebuildFromJsonl().
+     */
+    clearAll() {
+        this.db.exec(`
+      DELETE FROM events;
+      DELETE FROM projections;
+      DELETE FROM state_snapshots;
+      DELETE FROM projection_watermarks;
+      DELETE FROM seq_counter;
+    `);
+        this.db.exec(`INSERT OR IGNORE INTO seq_counter (id, last_seq) VALUES (1, 0)`);
+    }
+    /**
+     * Replace the entire events table with the supplied ordered list.
+     * Preserves caller-supplied seq numbers (JSONL heritage). seq_counter is
+     * reset to the max seq so future appends continue from the correct point.
+     */
+    rebuildEvents(orderedEvents) {
+        this.clearAll();
+        if (orderedEvents.length === 0)
+            return;
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            let maxSeq = 0;
+            for (const event of orderedEvents) {
+                this.insertEvent(event);
+                if (event.seq > maxSeq)
+                    maxSeq = event.seq;
+            }
+            const updateStmt = this.db.prepare('UPDATE seq_counter SET last_seq = ? WHERE id = 1');
+            updateStmt.run(maxSeq);
+            this.db.exec('COMMIT');
+        }
+        catch (err) {
+            this.db.exec('ROLLBACK');
+            throw err;
+        }
+    }
+}
+/**
+ * Immutable Append-Only Event Store
+ * All signals, tool results, guard evaluations, and state transitions are recorded here.
+ */
+export class EventStore {
+    events = [];
+    listeners = new Set();
+    storagePath = null;
+    sqliteDriver = null;
+    sqlitePath = null;
+    seqCounter = 0;
+    maxInMemoryEvents;
+    eventContext;
+    projectionWatermarks = new Map();
+    latestSnapshot = null;
+    maxJsonlBytes;
+    constructor(options = {}) {
+        this.maxInMemoryEvents = options.maxInMemoryEvents || 1000;
+        this.maxJsonlBytes = options.maxJsonlBytes || 10 * 1024 * 1024;
+        this.eventContext = {
+            skill_id: options.skillId,
+            run_id: options.runId || options.run_id || createSortableId(),
+            correlation_id: options.correlationId || createSortableId(),
+            request_id: options.requestId,
+            trace_parent: options.traceParent,
+            parent_run_id: options.parentRunId,
+            schema_version: options.schemaVersion || '1.0.3',
+        };
+        if (!options.inMemory) {
+            const workspaceDir = options.workspaceDir || process.cwd();
+            const scopeDir = options.skillId
+                ? path.join(workspaceDir, '.reactive', 'skills', options.skillId)
+                : path.join(workspaceDir, '.reactive');
+            const runScopedDir = options.runId
+                ? path.join(scopeDir, options.runId)
+                : scopeDir;
+            this.storagePath = options.storagePath || path.join(runScopedDir, 'events.jsonl');
+            if (options.enableSqlite || options.sqlitePath) {
+                const dbPath = options.sqlitePath || path.join(runScopedDir, 'events.db');
+                this.sqlitePath = dbPath;
+                this.sqliteDriver = new SQLiteStorageDriver(dbPath);
+            }
+            this.initializeStorage();
+        }
+        else if (options.enableSqlite) {
+            this.sqliteDriver = new SQLiteStorageDriver(':memory:');
+        }
+    }
+    initializeStorage() {
+        // SQLite is authoritative. If it already has events, load the recent
+        // sliding window and check JSONL for divergence before returning.
+        if (this.sqliteDriver) {
+            const sqliteLatestSeq = this.sqliteDriver.getLatestSequence();
+            if (sqliteLatestSeq > 0) {
+                this.seqCounter = sqliteLatestSeq;
+                this.events = this.sqliteDriver.getRecentEvents(this.maxInMemoryEvents);
+                // Divergence detection: JSONL may have events SQLite never saw (e.g.
+                // a prior run with SQLite disabled, or a failed SQLite write). If so,
+                // rebuild SQLite from JSONL so the authoritative store matches the
+                // audit log. Only run when JSONL and SQLite share a directory so an
+                // explicit sqlitePath in a different location isn't clobbered by a
+                // stray JSONL in the working directory.
+                if (this.storagePath && this.sqlitePath && path.dirname(this.storagePath) === path.dirname(this.sqlitePath)) {
+                    const jsonlStats = this.readJsonlStats();
+                    if (jsonlStats.count > 0 && jsonlStats.maxSeq > sqliteLatestSeq) {
+                        console.warn('EventStore: JSONL has events beyond SQLite (jsonl max seq=' +
+                            jsonlStats.maxSeq +
+                            ', sqlite max seq=' +
+                            sqliteLatestSeq +
+                            '). Rebuilding SQLite from JSONL.');
+                        this.rebuildFromJsonl();
+                        this.seqCounter = this.sqliteDriver.getLatestSequence();
+                        this.events = this.sqliteDriver.getRecentEvents(this.maxInMemoryEvents);
+                    }
+                    else if (jsonlStats.count > 0 && jsonlStats.maxSeq < sqliteLatestSeq) {
+                        // SQLite is authoritative; JSONL is a stale mirror. Optionally
+                        // backfill the audit log so it stays complete.
+                        this.syncJsonlToSqlite();
+                    }
+                }
+                return;
+            }
+        }
+        if (!this.storagePath)
+            return;
+        const dir = path.dirname(this.storagePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        const jsonlPaths = this.getJsonlPaths();
+        if (jsonlPaths.length > 0) {
+            const fileEvents = [];
+            for (const jsonlPath of jsonlPaths) {
+                const content = fs.readFileSync(jsonlPath, 'utf8');
+                const lines = content.split('\n').filter(l => l.trim().length > 0);
+                for (const line of lines) {
+                    try {
+                        const event = JSON.parse(line);
+                        fileEvents.push(event);
+                        if (event.seq > this.seqCounter) {
+                            this.seqCounter = event.seq;
+                        }
+                    }
+                    catch {
+                        // skip malformed lines
+                    }
+                }
+            }
+            this.events = fileEvents.slice(-this.maxInMemoryEvents);
+            // No SQLite yet but JSONL exists: seed SQLite from the audit log so the
+            // authoritative store is initialised from the same source of truth.
+            // Only when JSONL and SQLite share a directory (paired stores).
+            if (this.sqliteDriver && this.events.length > 0 && this.sqlitePath &&
+                path.dirname(this.storagePath) === path.dirname(this.sqlitePath)) {
+                this.rebuildFromJsonl();
+                this.seqCounter = this.sqliteDriver.getLatestSequence();
+                this.events = this.sqliteDriver.getRecentEvents(this.maxInMemoryEvents);
+            }
+        }
+    }
+    /**
+     * Scan all JSONL files for the authoritative max seq and event count.
+     * Returns { count: 0, maxSeq: 0 } when no JSONL is present.
+     */
+    readJsonlStats() {
+        if (!this.storagePath)
+            return { count: 0, maxSeq: 0 };
+        const paths = this.getJsonlPaths();
+        let count = 0;
+        let maxSeq = 0;
+        for (const jsonlPath of paths) {
+            if (!fs.existsSync(jsonlPath))
+                continue;
+            const content = fs.readFileSync(jsonlPath, 'utf8');
+            const lines = content.split('\n').filter(l => l.trim().length > 0);
+            for (const line of lines) {
+                try {
+                    const event = JSON.parse(line);
+                    count += 1;
+                    if (event.seq > maxSeq)
+                        maxSeq = event.seq;
+                }
+                catch {
+                    // skip malformed lines
+                }
+            }
+        }
+        return { count, maxSeq };
+    }
+    /**
+     * Rebuild SQLite from JSONL. Reads every JSONL file, deduplicates by event
+     * id (keeping the highest seq on conflict), clears SQLite, and re-inserts
+     * in seq order preserving original seq numbers. seq_counter is reset to the
+     * max seq. In-memory state is left untouched; callers must refresh it.
+     */
+    rebuildFromJsonl() {
+        if (!this.sqliteDriver) {
+            throw new Error('rebuildFromJsonl requires a SQLite driver to be enabled');
+        }
+        if (!this.storagePath) {
+            throw new Error('rebuildFromJsonl requires a storagePath (JSONL audit log)');
+        }
+        const events = this.readAllJsonlEvents();
+        const deduped = this.deduplicateById(events);
+        deduped.sort((a, b) => a.seq - b.seq);
+        this.sqliteDriver.rebuildEvents(deduped);
+        return deduped.length;
+    }
+    /**
+     * Read every event from every JSONL file (active + archived segments).
+     */
+    readAllJsonlEvents() {
+        if (!this.storagePath)
+            return [];
+        const paths = this.getJsonlPaths();
+        const events = [];
+        for (const jsonlPath of paths) {
+            if (!fs.existsSync(jsonlPath))
+                continue;
+            const content = fs.readFileSync(jsonlPath, 'utf8');
+            const lines = content.split('\n').filter(l => l.trim().length > 0);
+            for (const line of lines) {
+                try {
+                    events.push(JSON.parse(line));
+                }
+                catch {
+                    // skip malformed lines
+                }
+            }
+        }
+        return events;
+    }
+    /**
+     * Deduplicate events by id, keeping the entry with the highest seq.
+     */
+    deduplicateById(events) {
+        const byId = new Map();
+        for (const event of events) {
+            const existing = byId.get(event.id);
+            if (!existing || event.seq > existing.seq) {
+                byId.set(event.id, event);
+            }
+        }
+        return Array.from(byId.values());
+    }
+    /**
+     * Backfill JSONL with events SQLite has that JSONL is missing. SQLite is
+     * authoritative; this keeps the audit log complete when a JSONL write
+     * failed mid-write. Best-effort: failures are logged, not thrown.
+     */
+    syncJsonlToSqlite() {
+        if (!this.sqliteDriver || !this.storagePath)
+            return 0;
+        const sqliteEvents = this.sqliteDriver.queryEvents();
+        const sqliteIds = new Set(sqliteEvents.map(event => event.id));
+        const jsonlEvents = this.readAllJsonlEvents();
+        const jsonlIds = new Set(jsonlEvents.map(event => event.id));
+        const missing = sqliteEvents.filter(event => !jsonlIds.has(event.id));
+        if (missing.length === 0)
+            return 0;
+        try {
+            const line = missing.map(event => JSON.stringify(event)).join('\n') + '\n';
+            fs.appendFileSync(this.storagePath, line, 'utf8');
+            return missing.length;
+        }
+        catch (err) {
+            console.warn('EventStore: failed to backfill JSONL from SQLite', err);
+            return 0;
+        }
+    }
+    getJsonlPaths() {
+        if (!this.storagePath)
+            return [];
+        const dir = path.dirname(this.storagePath);
+        if (!fs.existsSync(dir))
+            return [];
+        const activeName = path.basename(this.storagePath);
+        const baseName = activeName.replace(/\.jsonl$/, '');
+        const archived = fs.readdirSync(dir)
+            .filter(name => new RegExp(`^${baseName}-\\d{6}\\.jsonl$`).test(name))
+            .sort()
+            .map(name => path.join(dir, name));
+        return [...archived, ...(fs.existsSync(this.storagePath) ? [this.storagePath] : [])];
+    }
+    rotateJsonlIfNeeded(nextLineBytes) {
+        if (!this.storagePath || !fs.existsSync(this.storagePath))
+            return;
+        const currentBytes = fs.statSync(this.storagePath).size;
+        if (currentBytes === 0 || currentBytes + nextLineBytes <= this.maxJsonlBytes)
+            return;
+        const dir = path.dirname(this.storagePath);
+        const baseName = path.basename(this.storagePath).replace(/\.jsonl$/, '');
+        let segment = 1;
+        let archivePath = path.join(dir, `${baseName}-${String(segment).padStart(6, '0')}.jsonl`);
+        while (fs.existsSync(archivePath)) {
+            segment += 1;
+            archivePath = path.join(dir, `${baseName}-${String(segment).padStart(6, '0')}.jsonl`);
+        }
+        fs.renameSync(this.storagePath, archivePath);
+    }
+    /**
+       * Append a new event to the immutable log.
+       *
+       * SQLite is the authoritative store when enabled; JSONL is an append-only
+       * audit mirror that can optionally be checked into git. If JSONL mirroring
+       * fails the run stays live because SQLite already persisted the event.
+       */
+    append(type, payload, metadata = {}) {
+        this.seqCounter = this.sqliteDriver ? this.sqliteDriver.nextSequence() : this.seqCounter + 1;
+        const event = {
+            id: createSortableId(),
+            seq: this.seqCounter,
+            timestamp: new Date().toISOString(),
+            type,
+            payload,
+            source: metadata.source,
+            causationId: metadata.causationId,
+            state: metadata.state,
+            event_id: '',
+            occurred_at: new Date().toISOString(),
+            event_type: type,
+            causation_id: metadata.causationId,
+            correlation_id: metadata.correlationId || this.eventContext.correlation_id,
+            request_id: metadata.requestId || this.eventContext.request_id,
+            trace_parent: metadata.traceParent || this.eventContext.trace_parent,
+            skill_id: metadata.skillId || this.eventContext.skill_id,
+            run_id: metadata.runId || this.eventContext.run_id,
+            parent_run_id: metadata.parentRunId || this.eventContext.parent_run_id,
+            schema_version: this.eventContext.schema_version,
+        };
+        event.event_id = event.id;
+        // 1. Authoritative SQLite persistence
+        if (this.sqliteDriver) {
+            try {
+                this.sqliteDriver.insertEvent(event);
+            }
+            catch (err) {
+                console.error('Error writing event to SQLite driver:', err);
+                throw new Error('Event persistence failed: SQLite write did not complete.', { cause: err });
+            }
+        }
+        // 2. Append to JSONL stream
+        if (this.storagePath) {
+            try {
+                const line = JSON.stringify(event) + '\n';
+                this.rotateJsonlIfNeeded(Buffer.byteLength(line, 'utf8'));
+                fs.appendFileSync(this.storagePath, line, 'utf8');
+            }
+            catch (err) {
+                if (this.sqliteDriver) {
+                    // SQLite is authoritative when enabled; keep execution live if optional JSONL mirroring fails.
+                    console.warn('Warning writing event to JSONL log; SQLite persistence remains authoritative.', err);
+                }
+                else {
+                    console.error('Error writing event to JSONL log:', err);
+                    throw new Error('Event persistence failed: JSONL write did not complete.', { cause: err });
+                }
+            }
+        }
+        // 3. Update bounded in-memory ring-buffer
+        this.events.push(event);
+        if (this.events.length > this.maxInMemoryEvents) {
+            this.events.shift(); // Evict oldest from RAM; preserved forever in SQLite/JSONL
+        }
+        // 4. Notify live listeners
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                console.error('Error in event store listener:', err);
+            }
+        }
+        return event;
+    }
+    /**
+     * Subscribe to new events
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /**
+     * Get all recorded events (delegates to SQLite if available, otherwise in-memory buffer)
+     */
+    getAll() {
+        if (this.sqliteDriver) {
+            return this.sqliteDriver.queryEvents();
+        }
+        return [...this.events];
+    }
+    getSince(seq) {
+        if (this.sqliteDriver) {
+            return this.sqliteDriver.queryEvents({ sinceSeq: seq });
+        }
+        return this.events.filter(event => event.seq > seq);
+    }
+    getLatestSequence() {
+        if (this.sqliteDriver) {
+            const latest = this.sqliteDriver.querySql('SELECT seq FROM events ORDER BY seq DESC LIMIT 1');
+            return latest.length > 0 ? Number(latest[0].seq) : 0;
+        }
+        return this.events.length > 0 ? this.events[this.events.length - 1].seq : 0;
+    }
+    getEventContext() {
+        return { ...this.eventContext };
+    }
+    saveProjectionWatermark(name, eventSeq, projectionVersion) {
+        const watermark = { eventSeq, projectionVersion };
+        this.projectionWatermarks.set(name, watermark);
+        this.sqliteDriver?.saveProjectionWatermark(name, eventSeq, projectionVersion);
+    }
+    getProjectionWatermark(name) {
+        if (this.sqliteDriver) {
+            return this.sqliteDriver.getProjectionWatermark(name);
+        }
+        return this.projectionWatermarks.get(name) || null;
+    }
+    saveSnapshot(seq, state, context) {
+        this.latestSnapshot = { seq, state, context: { ...context } };
+        if (this.sqliteDriver) {
+            this.sqliteDriver.saveSnapshot(seq, state, context);
+        }
+    }
+    getLatestSnapshot() {
+        if (this.sqliteDriver) {
+            return this.sqliteDriver.getLatestSnapshot();
+        }
+        return this.latestSnapshot ? { ...this.latestSnapshot, context: { ...this.latestSnapshot.context } } : null;
+    }
+    /**
+     * Query recorded events (relational index in SQLite, or in-memory filter)
+     */
+    query(filter = {}) {
+        if (this.sqliteDriver) {
+            return this.sqliteDriver.queryEvents(filter);
+        }
+        const filtered = this.events.filter(e => {
+            if (filter.type && e.type !== filter.type)
+                return false;
+            if (filter.state && e.state !== filter.state)
+                return false;
+            if (filter.sinceSeq !== undefined && e.seq <= filter.sinceSeq)
+                return false;
+            return true;
+        });
+        return filter.limit ? filtered.slice(0, filter.limit) : filtered;
+    }
+    /**
+     * Close storage drivers and release file handles
+     */
+    close() {
+        if (this.sqliteDriver) {
+            this.sqliteDriver.close();
+        }
+    }
+    /**
+     * Get SQLite driver instance if enabled
+     */
+    getSqliteDriver() {
+        return this.sqliteDriver;
+    }
+    /**
+     * Clear in-memory and file events (for test isolation)
+     */
+    clear() {
+        this.events = [];
+        this.seqCounter = 0;
+        this.projectionWatermarks.clear();
+        this.latestSnapshot = null;
+        if (this.sqliteDriver) {
+            this.sqliteDriver.clear();
+        }
+        if (this.storagePath && fs.existsSync(this.storagePath)) {
+            fs.unlinkSync(this.storagePath);
+        }
+        for (const jsonlPath of this.getJsonlPaths()) {
+            if (jsonlPath !== this.storagePath && fs.existsSync(jsonlPath))
+                fs.unlinkSync(jsonlPath);
+        }
+    }
+}