mcp-event-intelligence 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,78 @@
 
 All notable public changes are documented here.
 
+## [0.2.1] - 2026-09-20
+
+Patch hardening for shutdown determinism and multi-tenant verification.
+
+### Fixed
+
+- host shutdown now drains in-flight MCP polling, temporal/wake schedulers and persistent JSONL writes before returning;
+- prevents background writes from racing temporary-directory cleanup and causing intermittent `ENOTEMPTY` failures;
+- scoped isolation regression coverage now includes event source discovery, MCP client state/cursors, occurrences, audit records and wake visibility.
+
+### Clarified
+
+- the exported ERPNext helper is a typed MCP Events provider factory, not a credential-owning ERP connector;
+- the production authenticated ERPNext implementation remains in `world-capability-mcp`, where real data access, tenant/company filtering, pagination, cursors and timezone handling are implemented.
+
+## [0.2.0] - 2026-09-20
+
+Production-hardening release for shared Event Intelligence hosts.
+
+### Shared-host isolation
+
+- explicit `scopeId` partitions for tenant/workspace isolation;
+- scoped host views via `host.scope(scopeId)`;
+- isolated triggers, matches, event sources, cursors, deadlines, derived events and wake delivery state;
+- persistent scope restoration after restart;
+- root host documented as a trusted operator/control-plane capability.
+
+### Pluggable persistence
+
+- `createEventIntelligenceHost({ store })` now accepts an external storage backend;
+- `PersistentEventStore` remains the zero-dependency default;
+- scoped custom backends can implement `forScope(scopeId)`;
+- storage contract validates the operations required by Event Intelligence at startup.
+
+### Durable wake delivery
+
+- persisted wake-delivery state with `pending`, `claimed`, `retry_pending`, `delivered` and `dead_letter`;
+- atomic claim/lease API for concurrent workers;
+- bounded exponential retry and retry scheduler;
+- restart recovery without a new provider event;
+- reconciliation of a persisted runtime receipt after a crash without redelivering the wake;
+- the direct `EventProcessor` path now uses the same durable retry semantics.
+
+### Polling and load control
+
+- single-flight polling per MCP connection;
+- bounded `hasMore` page draining;
+- cursor persistence after every drained page;
+- explicit batch-limit reporting.
+
+### Internal modularity
+
+- composite store contracts extracted from `engine.ts`;
+- matching/correlation helpers extracted into a dedicated module;
+- derived-event cycle validation extracted into a graph module;
+- lifecycle, deadline and audit support extracted from the engine.
+
+### Provider coverage
+
+- new `mcp-event-intelligence/provider/erpnext` export;
+- provider-native ERPNext adapter for `erpnext.sales_invoice.submitted` and `erpnext.sales_order.created`;
+- schema-validation and provider-generalization regression coverage.
+
+### Verification
+
+- tenant-isolation tests with identical trigger IDs in separate scopes;
+- custom-store injection and restart persistence tests;
+- polling single-flight and bounded-batching tests;
+- retry, dead-letter, lease-contention and post-receipt crash-reconciliation tests;
+- ERPNext provider adapter tests;
+- CI, Security Scan, MCP Launch Check, Clean-room Smoke and Public Release Check green before release.
+
 ## [0.1.1] - 2026-09-20
 
 Provider integration patch.

package/README.md

@@ -4,7 +4,7 @@
 
 [![CI](https://github.com/sarooo17/event-intelligence/actions/workflows/ci.yml/badge.svg)](https://github.com/sarooo17/event-intelligence/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/mcp-event-intelligence.svg)](https://www.npmjs.com/package/mcp-event-intelligence)
-[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-v0.1.1-5b5bd6)](https://registry.modelcontextprotocol.io/?q=io.github.sarooo17%2Fevent-intelligence)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-v0.2.1-5b5bd6)](https://registry.modelcontextprotocol.io/?q=io.github.sarooo17%2Fevent-intelligence)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
 MCP Event Intelligence is an experimental event runtime for agents that need to react to **future conditions over multiple event sources** without keeping an LLM or agent loop alive.
@@ -55,6 +55,38 @@ const ei = await createEventIntelligenceHost({
 Event Intelligence enumerates the host registry automatically. GitHub, Gmail, private/company MCPs and future connections do not need to be configured again inside EI. Tools-only MCPs remain available to the agent and are ignored by the Events layer; Events-capable MCPs are attached automatically.
 
 
+### Shared hosts, tenant isolation and storage
+
+One EI host can serve many tenants/workspaces without sharing trigger state. Give each host-owned MCP connection a `scopeId` and give tenant-facing code only the corresponding scoped view:
+
+```js
+const tenant = await ei.scope('tenant-acme');
+
+await tenant.triggerControl.createTrigger({
+  definition,
+  connectionIds: ['acme-erp'],
+  actor,
+  owner,
+});
+
+const acmeConnections = tenant.mcpStatus();
+```
+
+The default reference store physically namespaces non-default scopes under separate persistent store partitions. Trigger IDs, match IDs, cursors, event sources, deadlines, derived events and wake delivery state are therefore resolved inside a scope rather than filtered out of a global result after the fact. The root host object is the trusted operator/control-plane capability; tenant code should receive a scoped view.
+
+Storage is injectable:
+
+```js
+const ei = await createEventIntelligenceHost({
+  store: myEventIntelligenceStore,
+  mcpRegistry,
+  wake,
+});
+```
+
+`PersistentEventStore` remains the zero-dependency default. A custom backend can implement `forScope(scopeId)` to return an isolated tenant view. For horizontally scaled workers, its wake-delivery claim/lease operations must be atomic across processes; the bundled JSONL store provides serialized atomicity inside one process and is a reference backend, not a distributed database.
+
+
 ## Add Events to an MCP provider
 
 Providers can expose the experimental Events boundary without reimplementing the generic JSON-RPC glue:
@@ -92,6 +124,36 @@ The package owns capability advertisement, `server/discover`, `events/list`, `ev
 
 This adapter remains experimental compatibility work around MCP Events; it is not a claim of finalized MCP Events conformance.
 
+
+An ERPNext-shaped **provider factory** is also exported:
+
+```js
+import {
+  createErpNextEventsProvider,
+} from 'mcp-event-intelligence/provider/erpnext';
+
+const events = createErpNextEventsProvider({
+  pollSalesInvoices: ({ cursor, maxEvents }) =>
+    erp.pollSubmittedInvoices({ cursor, maxEvents }),
+  pollSalesOrders: ({ cursor, maxEvents }) =>
+    erp.pollCreatedSalesOrders({ cursor, maxEvents }),
+});
+```
+
+This helper owns the MCP Events descriptors, schemas and response validation for
+`erpnext.sales_invoice.submitted` and `erpnext.sales_order.created`. It is
+**not** a credential-owning ERPNext connector: the host/provider must supply the
+actual data-access functions. That separation is intentional so Event
+Intelligence never duplicates provider authentication.
+
+The production proof that the abstraction works against a real ERP data layer
+lives in `sarooo17/world-capability-mcp`: its ERP Events implementation uses
+`createMcpEventsProvider` with authenticated ERPNext/Frappe record queries,
+tenant/company filters, opaque replay-safe cursors, pagination/`hasMore`,
+timezone normalization and deterministic occurrence IDs. The local factory in
+this package should therefore be read as a typed convenience API, not as the
+production ERP connector itself.
+
 ## What v0.1 implements
 
 ### Host-owned event sources
@@ -101,6 +163,8 @@ This adapter remains experimental compatibility work around MCP Events; it is no
 - experimental MCP Events capability discovery;
 - `events/list` and `events/poll`;
 - persistent opaque cursors;
+- per-scope source/cursor isolation for shared hosts;
+- single-flight polling per connection plus bounded `hasMore` batch draining;
 - automatic event-source registration;
 - dynamic attach/detach of host MCP clients;
 - provider-native compatibility adapters such as GitHub webhooks.
@@ -160,6 +224,8 @@ Derived event names are versioned contracts such as `release.ready@1`.
 
 An embedded harness can provide one in-process wake dispatcher that routes by `target.runtime`, `target.kind` and `target.id`; runtime-specific handlers remain available as a lower-level option. A standalone deployment can instead use signed HMAC callbacks. Both paths return a stable `runtimeReceiptId`.
 
+Runtime delivery is durable: a stable wake ID gets a persisted delivery record, a worker claims it with a lease, transient failures are retried with bounded exponential backoff, expired claims can be recovered after restart, and only an exhausted retry budget enters dead-letter. This prevents two workers sharing an atomic store from intentionally owning the same delivery at the same time. The runtime should still treat the stable wake ID as an idempotency key because no system can make an arbitrary external side effect transactionally exactly-once without cooperation from the receiver.
+
 ## Why this exists
 
 MCP Events is concerned with the event transport/subscription boundary. Event Intelligence explores the layer **above transport**:
@@ -195,6 +261,10 @@ The v0.1 acceptance suite verifies:
 - process shutdown while a temporal deadline is pending;
 - restart on the same datastore after the deadline;
 - wake recovery **without a new provider event**;
+- retry-state recovery after process restart and lease-based concurrent-worker exclusion;
+- shared-host tenant isolation with identical trigger IDs in different scopes;
+- bounded/single-flight provider polling;
+- provider-generalization coverage with ERPNext-shaped invoice/order events;
 - hash-linked audit verification.
 
 A separate live regression also verified real GitHub webhook ingress into the MCP EventOccurrence / composite fan-in path.
@@ -263,6 +333,11 @@ Standalone/core environment variables:
 | `RUNTIME_WAKE_TARGETS_JSON` | no | signed standalone runtime callbacks |
 | `GITHUB_WEBHOOK_SECRET` | no | verify GitHub webhook ingress |
 | `TYPESAFE_API_KEY` | no | bundled TypeSafe Jev semantic evaluator |
+| `WAKE_DELIVERY_MAX_ATTEMPTS` | no | maximum wake delivery attempts, default `5` |
+| `WAKE_DELIVERY_LEASE_MS` | no | claim lease duration, default `30000` |
+| `WAKE_RETRY_BASE_DELAY_MS` | no | first retry delay, default `1000` |
+| `WAKE_RETRY_MAX_DELAY_MS` | no | retry backoff cap, default `60000` |
+| `WAKE_RETRY_TICK_MS` | no | retry scheduler tick, default `1000` |
 
 Embedded hosts pass one MCP registry adapter. Event Intelligence discovers already-connected clients from that registry; provider MCP connection settings are not duplicated inside EI.
 
@@ -286,7 +361,7 @@ Absence/deadline progression uses Event Intelligence processing time. This separ
 
 The implementation does not claim theoretical distributed exactly-once delivery.
 
-It uses stable wake IDs, persistence, deduplication, runtime receipts and replay handling to provide effectively-once runtime activation in the validated reference scenarios.
+It uses stable wake IDs, persisted delivery state, atomic claim leases, bounded retries, runtime receipts and replay handling to provide effectively-once runtime activation in the validated reference scenarios.
 
 ### Derived event vs current state
 
@@ -298,7 +373,7 @@ v0.1 intentionally does not implement a mutable current-state/facts database.
 
 Read [SECURITY.md](SECURITY.md) and [docs/SECURITY-MODEL.md](docs/SECURITY-MODEL.md).
 
-In embedded mode, the host retains MCP authorization and credentials; Event Intelligence discovers only the client objects exposed through the host-provided MCP registry. The v0.1 reference store is JSONL and single-writer.
+In embedded mode, the host retains MCP authorization and credentials; Event Intelligence discovers only the client objects exposed through the host-provided MCP registry. Tenant-facing callers should receive only `host.scope(scopeId)`. The reference JSONL store is scope-partitioned and single-process; distributed custom stores must preserve scope isolation and atomic wake claims.
 
 ## MCP compatibility status
 
@@ -319,7 +394,7 @@ io.github.sarooo17/event-intelligence
 
 **v0.1 reference implementation / experimental.**
 
-The architecture is implemented and exercised end-to-end. Remaining work is primarily production storage/HA, broader host/provider evidence, scale benchmarks and upstream feedback.
+The architecture is implemented and exercised end-to-end. Storage is now injectable and scoped, while the bundled JSONL backend remains a single-process reference implementation. Remaining work is primarily production database adapters/HA validation, scale benchmarks and upstream feedback.
 
 ## Example
 

package/bin/mcp-event-intelligence.mjs

@@ -4,7 +4,7 @@ const args = process.argv.slice(2);
 const flags = new Set(args);
 
 if (flags.has('--version') || flags.has('-v')) {
-  console.log('0.1.1');
+  console.log('0.2.1');
   process.exit(0);
 }
 

package/dist/src/composite/derivedGraph.d.ts

@@ -0,0 +1,4 @@
+import type { CompositeTriggerDefinition } from '../intelligenceProtocol/triggerSchemas.js';
+export declare function assertNoDerivedEventCycle(existing: CompositeTriggerDefinition[], candidate: CompositeTriggerDefinition, getState?: (triggerId: string, version: string) => {
+    status: string;
+} | null): void;

package/dist/src/composite/derivedGraph.js

@@ -0,0 +1,46 @@
+const DERIVED_SERVER_ID = 'event-intelligence:derived';
+function eventNode(eventName, serverId) {
+    return `${serverId || DERIVED_SERVER_ID}::${eventName}`;
+}
+export function assertNoDerivedEventCycle(existing, candidate, getState) {
+    const definitions = [
+        ...existing.filter((definition) => {
+            const state = getState?.(definition.triggerId, definition.version);
+            return !state || state.status === 'active' || state.status === 'paused';
+        }),
+        candidate,
+    ].filter((definition) => definition.derivedEvent);
+    const graph = new Map();
+    for (const definition of definitions) {
+        const output = eventNode(definition.derivedEvent.name, DERIVED_SERVER_ID);
+        for (const clause of definition.clauses) {
+            const input = eventNode(clause.event, clause.serverId);
+            const edges = graph.get(input) ?? new Set();
+            edges.add(output);
+            graph.set(input, edges);
+        }
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const dfs = (node) => {
+        if (visiting.has(node))
+            return true;
+        if (visited.has(node))
+            return false;
+        visiting.add(node);
+        for (const next of graph.get(node) ?? []) {
+            if (dfs(next))
+                return true;
+        }
+        visiting.delete(node);
+        visited.add(node);
+        return false;
+    };
+    for (const node of graph.keys()) {
+        if (dfs(node)) {
+            const error = new Error(`Derived event graph contains a cycle involving ${node}`);
+            error.code = 'TRIGGER_DERIVED_EVENT_CYCLE';
+            throw error;
+        }
+    }
+}

package/dist/src/composite/engine.d.ts

@@ -1,63 +1,7 @@
 import type { SemanticEvaluator } from '../semantic/types.js';
 import { type CompositeTriggerDefinition, type TriggerMatchRecord } from '../intelligenceProtocol/triggerSchemas.js';
-export interface CompositeTriggerStore {
-    putTrigger(definition: CompositeTriggerDefinition): Promise<void>;
-    listTriggers(): CompositeTriggerDefinition[];
-    getTriggerState?(triggerId: string, version: string): {
-        status: 'active' | 'paused' | 'completed' | 'expired' | 'deleted';
-        owner?: unknown;
-        connectionIds?: string[];
-        fireCount?: number;
-        lastFiredAt?: string | null;
-        revision?: number;
-    } | null;
-    setTriggerState?(triggerId: string, version: string, status: 'active' | 'paused' | 'completed' | 'expired' | 'deleted', actor?: unknown, metadata?: Record<string, unknown>): Promise<unknown>;
-    appendTriggerMatch(record: TriggerMatchRecord): Promise<void>;
-    listTriggerMatches(triggerId?: string): TriggerMatchRecord[];
-    getTemporalDeadline?(deadlineId: string): {
-        deadlineId: string;
-        triggerId: string;
-        triggerVersion: string;
-        matchId: string;
-        conditionId: string;
-        dueAt: string;
-        status: 'pending' | 'cancelled' | 'fired';
-    } | null;
-    listTemporalDeadlines?(filter?: {
-        triggerId?: string;
-        matchId?: string;
-        status?: string;
-    }): Array<{
-        deadlineId: string;
-        triggerId: string;
-        triggerVersion: string;
-        matchId: string;
-        conditionId: string;
-        dueAt: string;
-        status: string;
-    }>;
-    putTemporalDeadline?(input: {
-        deadlineId: string;
-        triggerId: string;
-        triggerVersion: string;
-        matchId: string;
-        conditionId: string;
-        dueAt: string;
-        status: 'pending' | 'cancelled' | 'fired';
-    }): Promise<unknown>;
-    setTemporalDeadlineStatus?(deadlineId: string, status: 'pending' | 'cancelled' | 'fired'): Promise<unknown>;
-}
-export interface CompositeTriggerAudit {
-    appendAudit(input: {
-        auditId: string;
-        traceId: string;
-        timestamp: string;
-        kind: string;
-        entityType: 'trigger_match' | 'trigger';
-        entityId: string;
-        details?: Record<string, unknown>;
-    }): Promise<unknown>;
-}
+import type { CompositeTriggerAudit, CompositeTriggerStore } from './store.js';
+export type { CompositeTriggerAudit, CompositeTriggerStore, } from './store.js';
 export interface CompositeIngestResult {
     triggerId: string;
     match: TriggerMatchRecord | null;
@@ -68,6 +12,7 @@ export declare class CompositeTriggerEngine {
     private readonly store;
     private readonly evaluator;
     private readonly now;
+    private readonly support;
     constructor(store: CompositeTriggerStore & CompositeTriggerAudit, evaluator?: SemanticEvaluator | null, now?: () => Date);
     register(definitionInput: unknown): Promise<CompositeTriggerDefinition>;
     ingest(eventInput: unknown): Promise<CompositeIngestResult[]>;
@@ -76,12 +21,6 @@ export declare class CompositeTriggerEngine {
     private ingestTimerEvent;
     private applyEvent;
     private finalizeEligible;
-    private scheduleDeadlines;
-    private cancelDeadlinesForMatch;
-    private advanceLifecycleAfterEffect;
-    private lifecycleAllows;
-    private auditTriggerLifecycle;
     private newMatch;
     private latestMatch;
-    private audit;
 }