mcp-event-intelligence 0.4.0 → 0.6.0

package/scripts/lib/persistent-event-store.mjs

@@ -1,5 +1,15 @@
-import { appendFile, mkdir, readFile, readdir } from 'node:fs/promises';
+import {
+  appendFile,
+  mkdir,
+  readFile,
+  readdir,
+  rename,
+  writeFile,
+} from 'node:fs/promises';
 import path from 'node:path';
+import {
+  REFERENCE_STORE_CAPABILITIES,
+} from './store-capabilities.mjs';
 import {
   AuditChain,
   parseAuditRecord,
@@ -61,11 +71,17 @@ async function readJsonLines(filePath) {
   }
 }
 
+async function writeJsonLinesAtomic(filePath, records) {
+  const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  const content = records.length
+    ? `${records.map((record) => JSON.stringify(record)).join('\n')}\n`
+    : '';
+  await writeFile(tempPath, content, 'utf8');
+  await rename(tempPath, filePath);
+}
+
 export class PersistentEventStore {
   #queue = Promise.resolve();
-  #eventKeys = new Set();
-  #events = [];
-  #decisions = [];
   #wakes = [];
   #wakeDeliveries = new Map();
   #triggers = new Map();
@@ -79,14 +95,14 @@ export class PersistentEventStore {
   #temporalDeadlines = new Map();
   #derivedEvents = new Map();
   #derivedContracts = new Map();
+  #semanticDecisionCache = new Map();
+  #partitionLeases = new Map();
   #auditChain = new AuditChain();
   #scopeStores = new Map();
 
   constructor(dataDir) {
     this.dataDir = dataDir;
     this.files = {
-      events: path.join(dataDir, 'events.jsonl'),
-      decisions: path.join(dataDir, 'decisions.jsonl'),
       wakes: path.join(dataDir, 'wakes.jsonl'),
       wakeDeliveries: path.join(dataDir, 'wake-deliveries.jsonl'),
       triggers: path.join(dataDir, 'triggers.jsonl'),
@@ -98,10 +114,16 @@ export class PersistentEventStore {
       temporalDeadlines: path.join(dataDir, 'temporal-deadlines.jsonl'),
       derivedEvents: path.join(dataDir, 'derived-events.jsonl'),
       derivedContracts: path.join(dataDir, 'derived-contracts.jsonl'),
+      semanticDecisionCache: path.join(dataDir, 'semantic-decision-cache.jsonl'),
+      partitionLeases: path.join(dataDir, 'partition-leases.jsonl'),
       audit: path.join(dataDir, 'audit.jsonl'),
     };
   }
 
+  storeCapabilities() {
+    return { ...REFERENCE_STORE_CAPABILITIES };
+  }
+
   async forScope(scopeIdInput = DEFAULT_EVENT_SCOPE_ID) {
     const scopeId = normalizeEventScopeId(scopeIdInput);
     if (scopeId === DEFAULT_EVENT_SCOPE_ID) return this;
@@ -141,8 +163,6 @@ export class PersistentEventStore {
     await mkdir(this.dataDir, { recursive: true });
 
     const [
-      events,
-      decisions,
       wakes,
       wakeDeliveries,
       triggers,
@@ -154,10 +174,10 @@ export class PersistentEventStore {
       temporalDeadlines,
       derivedEvents,
       derivedContracts,
+      semanticDecisionCache,
+      partitionLeases,
       audit,
     ] = await Promise.all([
-      readJsonLines(this.files.events),
-      readJsonLines(this.files.decisions),
       readJsonLines(this.files.wakes),
       readJsonLines(this.files.wakeDeliveries),
       readJsonLines(this.files.triggers),
@@ -169,16 +189,16 @@ export class PersistentEventStore {
       readJsonLines(this.files.temporalDeadlines),
       readJsonLines(this.files.derivedEvents),
       readJsonLines(this.files.derivedContracts),
+      readJsonLines(this.files.semanticDecisionCache),
+      readJsonLines(this.files.partitionLeases),
       readJsonLines(this.files.audit),
     ]);
 
-    this.#events = events;
-    this.#decisions = decisions;
     this.#wakes = wakes;
 
     this.#wakeDeliveries = new Map();
     for (const raw of wakeDeliveries) {
-      if (!raw?.wakeId || !raw?.runtime || (!raw?.sourceId && !raw?.matchId)) continue;
+      if (!raw?.wakeId || !raw?.runtime || !raw?.matchId) continue;
       const status = [
         'pending',
         'claimed',
@@ -190,8 +210,6 @@ export class PersistentEventStore {
         : 'pending';
       const record = {
         wakeId: String(raw.wakeId),
-        sourceType: raw.sourceType === 'event' ? 'event' : 'composite',
-        sourceId: String(raw.sourceId || raw.matchId),
         matchId: raw.matchId ? String(raw.matchId) : '',
         triggerId: String(raw.triggerId || ''),
         triggerVersion: String(raw.triggerVersion || '1'),
@@ -379,19 +397,48 @@ export class PersistentEventStore {
       );
     }
 
-    this.#auditChain = new AuditChain(audit.map(parseAuditRecord));
+    this.#partitionLeases = new Map();
+    for (const raw of partitionLeases) {
+      if (!raw?.partitionKey) continue;
+      const key = String(raw.partitionKey);
+      if (raw.status === 'released') {
+        this.#partitionLeases.delete(key);
+        continue;
+      }
+      if (!raw.workerId || !raw.leaseUntil) continue;
+      this.#partitionLeases.set(key, {
+        partitionKey: key,
+        workerId: String(raw.workerId),
+        leaseUntil: String(raw.leaseUntil),
+        updatedAt: String(raw.updatedAt || new Date(0).toISOString()),
+        status: 'active',
+      });
+    }
 
-    for (const record of events) {
-      this.#eventKeys.add(this.#eventKey(record.lineage));
+    this.#semanticDecisionCache = new Map();
+    for (const raw of semanticDecisionCache) {
+      if (!raw?.key || !raw?.decision || typeof raw.decision !== 'object') {
+        continue;
+      }
+      this.#semanticDecisionCache.set(String(raw.key), {
+        key: String(raw.key),
+        decision: raw.decision,
+        createdAt: String(
+          raw.createdAt || raw.updatedAt || new Date(0).toISOString()
+        ),
+        updatedAt: String(
+          raw.updatedAt || raw.createdAt || new Date(0).toISOString()
+        ),
+      });
     }
 
+    this.#auditChain = new AuditChain(audit.map(parseAuditRecord));
+
     if (!(await this.#auditChain.verify())) {
       throw new Error('Persistent audit chain verification failed');
     }
 
     return {
-      events: events.length,
-      decisions: decisions.length,
       wakes: wakes.length,
       wakeDeliveries: this.#wakeDeliveries.size,
       triggers: this.#triggers.size,
@@ -404,30 +451,12 @@ export class PersistentEventStore {
       temporalDeadlines: this.#temporalDeadlines.size,
       derivedEvents: this.#derivedEvents.size,
       derivedContracts: this.#derivedContracts.size,
+      semanticDecisionCache: this.#semanticDecisionCache.size,
+      partitionLeases: this.#partitionLeases.size,
       audit: audit.length,
     };
   }
 
-  async registerEvent(record) {
-    return this.#serialized(async () => {
-      const key = this.#eventKey(record.lineage);
-      if (this.#eventKeys.has(key)) return false;
-
-      this.#eventKeys.add(key);
-      this.#events.push(record);
-      await appendFile(this.files.events, `${JSON.stringify(record)}\n`, 'utf8');
-      return true;
-    });
-  }
-
-  async appendDecision(record) {
-    return this.#serialized(async () => {
-      this.#decisions.push(record);
-      await appendFile(this.files.decisions, `${JSON.stringify(record)}\n`, 'utf8');
-      return record;
-    });
-  }
-
   async appendWake(record) {
     return this.#serialized(async () => {
       this.#wakes.push(record);
@@ -452,12 +481,7 @@ export class PersistentEventStore {
         }
         if (record.status === 'delivered') {
           const latestWake = this.latestWake(record.wakeId);
-          const wakeFinalized =
-            latestWake?.status === 'delivered' ||
-            latestWake?.status === 'handled';
-          if (record.sourceType === 'event') {
-            return !wakeFinalized;
-          }
+          const wakeFinalized = latestWake?.status === 'delivered';
           const match = this.#triggerMatches.get(record.matchId);
           return !wakeFinalized || match?.status !== 'fired';
         }
@@ -472,15 +496,10 @@ export class PersistentEventStore {
   async ensureWakeDelivery(input) {
     return this.#serialized(async () => {
       const wakeId = String(input.wakeId || '');
-      const sourceType = input.sourceType === 'event' ? 'event' : 'composite';
       const matchId = String(input.matchId || '');
-      const sourceId = String(input.sourceId || matchId || '');
       const runtime = String(input.runtime || '');
-      if (!wakeId || !sourceId || !runtime) {
-        throw new Error('Wake delivery requires wakeId, sourceId and runtime');
-      }
-      if (sourceType === 'composite' && !matchId) {
-        throw new Error('Composite wake delivery requires matchId');
+      if (!wakeId || !matchId || !runtime) {
+        throw new Error('Wake delivery requires wakeId, matchId and runtime');
       }
       const existing = this.#wakeDeliveries.get(wakeId);
       if (existing) return existing;
@@ -488,8 +507,6 @@ export class PersistentEventStore {
       const now = String(input.now ?? new Date().toISOString());
       const record = {
         wakeId,
-        sourceType,
-        sourceId,
         matchId,
         triggerId: String(input.triggerId || ''),
         triggerVersion: String(input.triggerVersion || '1'),
@@ -1077,6 +1094,162 @@ export class PersistentEventStore {
     });
   }
 
+  getPartitionLease(partitionKeyInput) {
+    return this.#partitionLeases.get(String(partitionKeyInput || '')) ?? null;
+  }
+
+  async claimPartitionLease(partitionKeyInput, {
+    workerId,
+    now = new Date().toISOString(),
+    leaseMs = 30000,
+  } = {}) {
+    return this.#serialized(async () => {
+      const partitionKey = String(partitionKeyInput || '').trim();
+      const owner = String(workerId || '').trim();
+      if (!partitionKey || !owner) {
+        throw new Error('Partition lease requires partitionKey and workerId');
+      }
+      const nowMs = Date.parse(now);
+      const current = this.#partitionLeases.get(partitionKey);
+      if (
+        current &&
+        current.workerId !== owner &&
+        Date.parse(current.leaseUntil) > nowMs
+      ) {
+        return null;
+      }
+      const record = {
+        partitionKey,
+        workerId: owner,
+        leaseUntil: new Date(
+          nowMs + Math.max(1000, Number(leaseMs) || 30000),
+        ).toISOString(),
+        updatedAt: now,
+        status: 'active',
+      };
+      this.#partitionLeases.set(partitionKey, record);
+      await appendFile(
+        this.files.partitionLeases,
+        `${JSON.stringify(record)}\n`,
+        'utf8',
+      );
+      return record;
+    });
+  }
+
+  async renewPartitionLease(partitionKeyInput, {
+    workerId,
+    now = new Date().toISOString(),
+    leaseMs = 30000,
+  } = {}) {
+    return this.#serialized(async () => {
+      const partitionKey = String(partitionKeyInput || '').trim();
+      const owner = String(workerId || '').trim();
+      const current = this.#partitionLeases.get(partitionKey);
+      if (!current || current.workerId !== owner) return null;
+      const record = {
+        ...current,
+        leaseUntil: new Date(
+          Date.parse(now) + Math.max(1000, Number(leaseMs) || 30000),
+        ).toISOString(),
+        updatedAt: now,
+      };
+      this.#partitionLeases.set(partitionKey, record);
+      await appendFile(
+        this.files.partitionLeases,
+        `${JSON.stringify(record)}\n`,
+        'utf8',
+      );
+      return record;
+    });
+  }
+
+  async releasePartitionLease(partitionKeyInput, {
+    workerId,
+    now = new Date().toISOString(),
+  } = {}) {
+    return this.#serialized(async () => {
+      const partitionKey = String(partitionKeyInput || '').trim();
+      const owner = String(workerId || '').trim();
+      const current = this.#partitionLeases.get(partitionKey);
+      if (!current || current.workerId !== owner) return false;
+      this.#partitionLeases.delete(partitionKey);
+      await appendFile(
+        this.files.partitionLeases,
+        `${JSON.stringify({
+          partitionKey,
+          workerId: owner,
+          status: 'released',
+          updatedAt: now,
+        })}\n`,
+        'utf8',
+      );
+      return true;
+    });
+  }
+
+  async compactMutableState() {
+    return this.#serialized(async () => {
+      const snapshots = [
+        [this.files.wakeDeliveries, [...this.#wakeDeliveries.values()]],
+        [this.files.triggerStates, [...this.#triggerStates.values()]],
+        [this.files.eventSources, [...this.#eventSources.values()]],
+        [this.files.mcpClientStates, [...this.#mcpClientStates.values()]],
+        [this.files.temporalDeadlines, [...this.#temporalDeadlines.values()]],
+        [this.files.derivedContracts, [...this.#derivedContracts.values()]],
+        [this.files.semanticDecisionCache, [...this.#semanticDecisionCache.values()]],
+        [this.files.partitionLeases, [...this.#partitionLeases.values()]],
+      ];
+      for (const [filePath, records] of snapshots) {
+        await writeJsonLinesAtomic(filePath, records);
+      }
+      return {
+        ok: true,
+        compacted: snapshots.map(([filePath, records]) => ({
+          file: path.basename(filePath),
+          records: records.length,
+        })),
+      };
+    });
+  }
+
+  getSemanticDecisionCache(keyInput) {
+    const record = this.#semanticDecisionCache.get(
+      String(keyInput || '')
+    );
+    return record?.decision ?? null;
+  }
+
+  async putSemanticDecisionCache(keyInput, decision) {
+    return this.#serialized(async () => {
+      const key = String(keyInput || '').trim();
+      if (!key || !decision || typeof decision !== 'object') {
+        throw new Error(
+          'Semantic decision cache requires key and decision'
+        );
+      }
+      const previous = this.#semanticDecisionCache.get(key);
+      const now = new Date().toISOString();
+      const record = {
+        key,
+        decision,
+        createdAt: previous?.createdAt ?? now,
+        updatedAt: now,
+      };
+      this.#semanticDecisionCache.set(key, record);
+      await appendFile(
+        this.files.semanticDecisionCache,
+        `${JSON.stringify(record)}\n`,
+        'utf8',
+      );
+      return record;
+    });
+  }
+
+  semanticDecisionCacheSize() {
+    return this.#semanticDecisionCache.size;
+  }
+
   async appendAudit(input) {
     return this.#serialized(async () => {
       const record = await this.#auditChain.append(input);
@@ -1094,8 +1267,6 @@ export class PersistentEventStore {
 
   trace(traceId) {
     return {
-      events: this.#events.filter((record) => record.lineage?.traceId === traceId),
-      decisions: this.#decisions.filter((record) => record.traceId === traceId),
       wakes: this.#wakes.filter((record) => record.traceId === traceId),
       triggerMatches: this.listTriggerMatches().filter((record) =>
         record.sourceEvents.some((event) => event.traceId === traceId),
@@ -1128,10 +1299,6 @@ export class PersistentEventStore {
     await this.drain();
   }
 
-  #eventKey(lineage) {
-    return `${lineage.environmentId}:${lineage.subscriptionId}:${lineage.sourceEventId}`;
-  }
-
   #triggerKey(definition) {
     return `${definition.triggerId}@${definition.version}`;
   }

package/scripts/lib/store-capabilities.mjs

@@ -0,0 +1,88 @@
+export const EVENT_INTELLIGENCE_STORE_CAPABILITIES_VERSION = '1';
+
+export const UNDECLARED_STORE_CAPABILITIES = Object.freeze({
+  version: EVENT_INTELLIGENCE_STORE_CAPABILITIES_VERSION,
+  sharedState: 'none',
+  scopeIsolation: 'unknown',
+  wakeClaims: 'unknown',
+  partitionLeases: 'none',
+  mutableCompaction: 'none',
+  readModel: 'undeclared',
+});
+
+export const REFERENCE_STORE_CAPABILITIES = Object.freeze({
+  version: EVENT_INTELLIGENCE_STORE_CAPABILITIES_VERSION,
+  sharedState: 'single-process',
+  scopeIsolation: 'strong',
+  wakeClaims: 'process-atomic',
+  partitionLeases: 'process-atomic',
+  mutableCompaction: 'atomic-snapshot',
+  readModel: 'synchronous-materialized',
+});
+
+export function describeStoreCapabilities(store) {
+  if (
+    store &&
+    typeof store.storeCapabilities === 'function'
+  ) {
+    return {
+      ...UNDECLARED_STORE_CAPABILITIES,
+      ...store.storeCapabilities(),
+    };
+  }
+  return { ...UNDECLARED_STORE_CAPABILITIES };
+}
+
+export function validateSharedStoreCapabilities(store) {
+  const capabilities = describeStoreCapabilities(store);
+  const errors = [];
+
+  if (capabilities.sharedState !== 'strong') {
+    errors.push(
+      `sharedState must be strong; received ${capabilities.sharedState}`,
+    );
+  }
+  if (capabilities.scopeIsolation !== 'strong') {
+    errors.push(
+      `scopeIsolation must be strong; received ${capabilities.scopeIsolation}`,
+    );
+  }
+  if (capabilities.wakeClaims !== 'distributed-atomic') {
+    errors.push(
+      `wakeClaims must be distributed-atomic; received ${capabilities.wakeClaims}`,
+    );
+  }
+  if (capabilities.partitionLeases !== 'distributed-atomic') {
+    errors.push(
+      `partitionLeases must be distributed-atomic; received ${capabilities.partitionLeases}`,
+    );
+  }
+  for (const method of [
+    'claimPartitionLease',
+    'renewPartitionLease',
+    'releasePartitionLease',
+  ]) {
+    if (typeof store?.[method] !== 'function') {
+      errors.push(`shared store is missing ${method}()`);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    capabilities,
+    errors,
+  };
+}
+
+export function assertSharedStoreCapabilities(store) {
+  const result = validateSharedStoreCapabilities(store);
+  if (result.ok) return result.capabilities;
+
+  const error = new Error(
+    'Event Intelligence shared-store requirements failed: ' +
+      result.errors.join('; '),
+  );
+  error.code = 'EVENT_INTELLIGENCE_SHARED_STORE_REQUIRED';
+  error.details = result;
+  throw error;
+}

package/scripts/lib/store-conformance.mjs

@@ -0,0 +1,127 @@
+import assert from 'node:assert/strict';
+import {
+  describeStoreCapabilities,
+  validateSharedStoreCapabilities,
+} from './store-capabilities.mjs';
+
+export async function runStoreConformance({
+  createStore,
+  expectShared = false,
+} = {}) {
+  if (typeof createStore !== 'function') {
+    throw new Error('runStoreConformance requires createStore()');
+  }
+
+  const store = await createStore();
+  if (typeof store.init === 'function') await store.init();
+
+  const report = {
+    schema: 'event-intelligence.store-conformance.v1',
+    capabilities: describeStoreCapabilities(store),
+    checks: [],
+  };
+
+  const check = async (name, fn) => {
+    await fn();
+    report.checks.push({ name, ok: true });
+  };
+
+  await check('trigger-state round trip', async () => {
+    await store.putTrigger({
+      protocolVersion: '0.1.0',
+      schemaVersion: 'trigger.v0.1',
+      triggerId: 'store-conf-trigger',
+      version: '1',
+      conditionOnly: true,
+      clauses: [{
+        id: 'event',
+        event: 'store.conformance.event',
+        arguments: {},
+        where: [],
+      }],
+      expression: { kind: 'anyOf', refs: ['event'] },
+      temporal: [],
+      withinMs: 60000,
+      lifecycle: {
+        oneShot: false,
+        cooldownMs: 0,
+        completeOnGoal: false,
+      },
+    });
+    await store.setTriggerState(
+      'store-conf-trigger',
+      '1',
+      'paused',
+      { type: 'system', principal_id: 'conformance' },
+    );
+    assert.equal(
+      (await store.getTriggerState('store-conf-trigger', '1')).status,
+      'paused',
+    );
+  });
+
+  await check('wake claim exclusion', async () => {
+    await store.ensureWakeDelivery({
+      wakeId: 'store-conf-wake',
+      sourceType: 'event',
+      sourceId: 'source-1',
+      runtime: 'conformance',
+      now: '2026-09-30T00:00:00.000Z',
+    });
+    const [a, b] = await Promise.all([
+      store.claimWakeDelivery('store-conf-wake', {
+        workerId: 'a',
+        now: '2026-09-30T00:00:00.000Z',
+        leaseMs: 30000,
+      }),
+      store.claimWakeDelivery('store-conf-wake', {
+        workerId: 'b',
+        now: '2026-09-30T00:00:00.000Z',
+        leaseMs: 30000,
+      }),
+    ]);
+    assert.equal([a, b].filter(Boolean).length, 1);
+  });
+
+  if (
+    typeof store.claimPartitionLease === 'function' &&
+    typeof store.releasePartitionLease === 'function'
+  ) {
+    await check('partition lease exclusion', async () => {
+      const [a, b] = await Promise.all([
+        store.claimPartitionLease('partition-1', {
+          workerId: 'a',
+          now: '2026-09-30T00:00:00.000Z',
+          leaseMs: 30000,
+        }),
+        store.claimPartitionLease('partition-1', {
+          workerId: 'b',
+          now: '2026-09-30T00:00:00.000Z',
+          leaseMs: 30000,
+        }),
+      ]);
+      assert.equal([a, b].filter(Boolean).length, 1);
+      const owner = a ? 'a' : 'b';
+      await store.releasePartitionLease('partition-1', {
+        workerId: owner,
+      });
+    });
+  }
+
+  if (typeof store.compactMutableState === 'function') {
+    await check('mutable-state compaction', async () => {
+      const result = await store.compactMutableState();
+      assert.equal(result?.ok, true);
+    });
+  }
+
+  const shared = validateSharedStoreCapabilities(store);
+  if (expectShared) {
+    assert.equal(shared.ok, true, shared.errors.join('; '));
+  }
+  report.sharedReady = shared.ok;
+  report.sharedErrors = shared.errors;
+
+  if (typeof store.close === 'function') await store.close();
+  return report;
+}

package/scripts/lib/temporal-deadline-scheduler.mjs

@@ -19,14 +19,14 @@ export class TemporalDeadlineScheduler {
 
     try {
       const now = this.now();
-      const due = this.store.listDueTemporalDeadlines(now.toISOString());
+      const due = await this.store.listDueTemporalDeadlines(now.toISOString());
       const outcomes = [];
 
       for (const deadline of due) {
-        const latest = this.store.getTemporalDeadline(deadline.deadlineId);
+        const latest = await this.store.getTemporalDeadline(deadline.deadlineId);
         if (!latest || latest.status !== 'pending') continue;
 
-        const match = this.store.listTriggerMatches(deadline.triggerId)
+        const match = (await this.store.listTriggerMatches(deadline.triggerId))
           .filter((record) => record.matchId === deadline.matchId)
           .sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt))[0];