mcp-event-intelligence 0.1.0

package/scripts/lib/composite-event-consumer.mjs

@@ -0,0 +1,172 @@
+import {
+  mcpOccurrenceToCorrelatableEvent,
+} from '../../dist/src/mcpEvents/consumer.js';
+
+export class CompositeEventConsumer {
+  constructor({
+    store,
+    triggerEngine,
+    wakeCoordinator = null,
+    wakeCoordinators = null,
+    derivedEventCoordinator = null,
+    processor = null,
+    maxDerivedDepth = 16,
+  }) {
+    this.store = store;
+    this.triggerEngine = triggerEngine;
+    this.wakeCoordinator = wakeCoordinator;
+    this.wakeCoordinators = wakeCoordinators instanceof Map
+      ? wakeCoordinators
+      : new Map();
+    this.derivedEventCoordinator = derivedEventCoordinator;
+    this.processor = processor;
+    this.maxDerivedDepth = Math.max(1, Number(maxDerivedDepth) || 16);
+  }
+
+  coordinatorFor(runtime) {
+    const configured = this.wakeCoordinators.get(runtime);
+    if (configured) return configured;
+    return this.wakeCoordinator;
+  }
+
+  async ingestMcpOccurrence({
+    event,
+    serverId,
+    provider,
+    traceId,
+  }) {
+    const correlatable = await mcpOccurrenceToCorrelatableEvent(
+      event,
+      {
+        traceId,
+        ...(provider ? { provider } : {}),
+        ...(serverId ? { serverId } : {}),
+      },
+    );
+
+    return this.ingestCorrelatable(correlatable);
+  }
+
+  async ingestCorrelatable(event, context = {}) {
+    const derivedDepth = Number(context.derivedDepth ?? 0);
+    const results = await this.triggerEngine.ingest(event);
+    const deliveries = [];
+    const derivedEvents = [];
+
+    for (const result of results) {
+      if (!result.matched || !result.match) continue;
+
+      const definition = this.store.listTriggers().find(
+        (candidate) =>
+          candidate.triggerId === result.match.triggerId &&
+          candidate.version === result.match.triggerVersion,
+      );
+
+      if (!definition) {
+        deliveries.push({
+          triggerId: result.triggerId,
+          matchId: result.match.matchId,
+          wakeId: null,
+          status: 'trigger_definition_missing',
+          runtimeReceiptId: null,
+        });
+        continue;
+      }
+
+      if (definition.derivedEvent && this.derivedEventCoordinator) {
+        if (derivedDepth >= this.maxDerivedDepth) {
+          const error = new Error(
+            `Derived event chain exceeded max depth ${this.maxDerivedDepth}`,
+          );
+          error.code = 'DERIVED_EVENT_CHAIN_DEPTH_EXCEEDED';
+          throw error;
+        }
+
+        const emission = await this.derivedEventCoordinator.emitMatched(
+          result.match,
+          definition,
+        );
+        const derivedRecord = emission.record;
+        const summary = {
+          triggerId: result.triggerId,
+          matchId: result.match.matchId,
+          status: emission.status,
+          accepted: emission.accepted,
+          eventId: derivedRecord?.event.sourceEventId ?? null,
+          eventName: derivedRecord?.event.name ?? definition.derivedEvent.name,
+          nested: null,
+        };
+
+        if (derivedRecord) {
+          // Re-enter even on replay. Downstream match/event idempotency makes this
+          // restart-safe if the process crashed after persistence but before fan-out.
+          summary.nested = await this.ingestCorrelatable(
+            derivedRecord.event,
+            { derivedDepth: derivedDepth + 1 },
+          );
+
+          if (!definition.target) {
+            await this.triggerEngine.markDerivedEmitted(
+              result.match.matchId,
+              derivedRecord.event.sourceEventId,
+            );
+          }
+        }
+
+        derivedEvents.push(summary);
+      }
+
+      if (!definition.target) {
+        continue;
+      }
+
+      const coordinator = this.coordinatorFor(definition.target.runtime);
+      if (!coordinator) {
+        deliveries.push({
+          triggerId: result.triggerId,
+          matchId: result.match.matchId,
+          wakeId: null,
+          status: 'runtime_unconfigured',
+          runtimeReceiptId: null,
+        });
+        continue;
+      }
+
+      const delivery = await coordinator.deliverMatched(result.match);
+      const persistedWake = delivery.wake;
+
+      if (
+        persistedWake?.status === 'delivered' &&
+        persistedWake.runtimeReceiptId &&
+        this.processor
+      ) {
+        const handled = await this.processor.acknowledgeWake(
+          persistedWake.wakeId,
+          persistedWake.runtimeReceiptId,
+        );
+        deliveries.push({
+          triggerId: result.triggerId,
+          matchId: result.match.matchId,
+          wakeId: handled.wakeId,
+          status: handled.status,
+          runtimeReceiptId: handled.runtimeReceiptId ?? null,
+        });
+      } else {
+        deliveries.push({
+          triggerId: result.triggerId,
+          matchId: result.match.matchId,
+          wakeId: persistedWake?.wakeId ?? null,
+          status: delivery.status,
+          runtimeReceiptId: persistedWake?.runtimeReceiptId ?? null,
+        });
+      }
+    }
+
+    return {
+      event,
+      results,
+      deliveries,
+      derivedEvents,
+    };
+  }
+}

package/scripts/lib/composite-wake-coordinator.mjs

@@ -0,0 +1,185 @@
+import {
+  WakeRecordSchema,
+  sha256Hex,
+} from '../../dist/src/intelligenceProtocol/index.js';
+import {
+  buildGenericRuntimeWakePacket,
+} from './generic-runtime-wake.mjs';
+
+async function stableId(prefix, value) {
+  const hash = await sha256Hex(value);
+  return `${prefix}_${hash.slice(0, 24)}`;
+}
+
+export class CompositeWakeCoordinator {
+  constructor({
+    store,
+    triggerEngine,
+    deliverer = null,
+    packetBuilder = buildGenericRuntimeWakePacket,
+    now = () => new Date(),
+  }) {
+    this.store = store;
+    this.triggerEngine = triggerEngine;
+    this.deliverer = deliverer;
+    this.packetBuilder = packetBuilder;
+    this.now = now;
+  }
+
+  async deliverMatched(match) {
+    if (!match || (match.status !== 'matched' && match.status !== 'fired')) {
+      return { status: 'not_matched', wake: null };
+    }
+
+    if (match.status === 'fired') {
+      const existing = match.firedWakeId
+        ? this.store.latestWake(match.firedWakeId)
+        : null;
+      return {
+        status: 'already_fired',
+        wake: existing,
+      };
+    }
+
+    const definition = this.store.listTriggers().find(
+      (candidate) =>
+        candidate.triggerId === match.triggerId &&
+        candidate.version === match.triggerVersion,
+    );
+    if (!definition) {
+      throw new Error(
+        `Trigger definition not found for ${match.triggerId}@${match.triggerVersion}`,
+      );
+    }
+
+    if (!definition.target) {
+      return { status: 'no_runtime_target', wake: null };
+    }
+
+    const wakeId = await stableId(
+      'wake',
+      `composite:${match.matchId}:${definition.target.runtime}:${definition.target.id}`,
+    );
+
+    const existing = this.store.latestWake(wakeId);
+    if (existing?.status === 'handled' || existing?.status === 'delivered') {
+      if (match.status !== 'fired') {
+        await this.triggerEngine.markFired(match.matchId, wakeId);
+      }
+      return {
+        status: existing.status === 'handled' ? 'handled' : 'wake_delivered',
+        wake: existing,
+      };
+    }
+
+    const queued = WakeRecordSchema.parse({
+      wakeId,
+      traceId: match.sourceEvents[0]?.traceId ?? match.matchId,
+      decisionId: null,
+      subscriptionId: `trigger:${match.triggerId}`,
+      sourceEventId: match.matchId,
+      createdAt: this.now().toISOString(),
+      target: definition.target,
+      status: 'queued',
+    });
+
+    if (!existing || existing.status === 'dead_letter') {
+      await this.store.appendWake(queued);
+      await this.store.appendAudit({
+        auditId: await stableId(
+          'audit',
+          `${wakeId}:queued:${this.store.auditLength()}`,
+        ),
+        traceId: queued.traceId,
+        timestamp: this.now().toISOString(),
+        kind: 'wake.queued',
+        entityType: 'wake',
+        entityId: wakeId,
+        toState: 'wake_queued',
+        details: {
+          triggerMatchId: match.matchId,
+          triggerId: match.triggerId,
+          composite: true,
+        },
+      });
+    }
+
+    if (!this.deliverer) {
+      return { status: 'wake_queued', wake: queued };
+    }
+
+    try {
+      const packet = this.packetBuilder({
+        wakeId,
+        match,
+        definition,
+      });
+      const receipt = await this.deliverer(packet);
+
+      const delivered = WakeRecordSchema.parse({
+        ...queued,
+        createdAt: this.now().toISOString(),
+        status: 'delivered',
+        runtimeReceiptId: receipt.runtimeReceiptId,
+      });
+      await this.store.appendWake(delivered);
+      await this.store.appendAudit({
+        auditId: await stableId(
+          'audit',
+          `${wakeId}:delivered:${this.store.auditLength()}`,
+        ),
+        traceId: delivered.traceId,
+        timestamp: this.now().toISOString(),
+        kind: 'wake.delivered',
+        entityType: 'wake',
+        entityId: wakeId,
+        fromState: 'wake_queued',
+        toState: 'wake_delivered',
+        details: {
+          triggerMatchId: match.matchId,
+          runtimeReceiptId: delivered.runtimeReceiptId,
+          duplicate: receipt.duplicate === true,
+          composite: true,
+        },
+      });
+
+      await this.triggerEngine.markFired(match.matchId, wakeId);
+
+      return {
+        status: 'wake_delivered',
+        wake: delivered,
+        packet,
+      };
+    } catch (error) {
+      const deadLetter = WakeRecordSchema.parse({
+        ...queued,
+        createdAt: this.now().toISOString(),
+        status: 'dead_letter',
+      });
+      await this.store.appendWake(deadLetter);
+      await this.store.appendAudit({
+        auditId: await stableId(
+          'audit',
+          `${wakeId}:dead-letter:${this.store.auditLength()}`,
+        ),
+        traceId: deadLetter.traceId,
+        timestamp: this.now().toISOString(),
+        kind: 'wake.dead_letter',
+        entityType: 'wake',
+        entityId: wakeId,
+        fromState: 'wake_queued',
+        toState: 'dead_letter',
+        details: {
+          triggerMatchId: match.matchId,
+          message: error instanceof Error ? error.message : 'wake delivery failed',
+          composite: true,
+        },
+      });
+      return {
+        status: 'dead_letter',
+        wake: deadLetter,
+        error,
+      };
+    }
+  }
+}

package/scripts/lib/derived-contract-registry.mjs

@@ -0,0 +1,210 @@
+import {
+  sha256Hex,
+} from '../../dist/src/intelligenceProtocol/index.js';
+
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value
+      .map(canonicalize)
+      .sort((a, b) =>
+        JSON.stringify(a).localeCompare(JSON.stringify(b))
+      );
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, canonicalize(value[key])]),
+    );
+  }
+  return value;
+}
+
+function sameProducer(left, right) {
+  return (
+    left.triggerId === right.triggerId &&
+    left.triggerVersion === right.triggerVersion
+  );
+}
+
+export class DerivedContractRegistry {
+  constructor({
+    store,
+    audit = null,
+    now = () => new Date(),
+  }) {
+    this.store = store;
+    this.audit = audit;
+    this.now = now;
+  }
+
+  async fingerprint(payloadSchema) {
+    return sha256Hex(canonicalize(payloadSchema ?? {}));
+  }
+
+  list(eventName) {
+    return this.store.listDerivedContracts(eventName);
+  }
+
+  get(eventName, contractVersion) {
+    return this.store.getDerivedContract(eventName, contractVersion);
+  }
+
+  async assertCompatible({
+    eventName,
+    contractVersion,
+    payloadSchema,
+  }) {
+    const canonicalSchema = canonicalize(payloadSchema ?? {});
+    const schemaFingerprint = await this.fingerprint(canonicalSchema);
+    const existing = this.get(eventName, contractVersion);
+    if (
+      existing &&
+      existing.schemaFingerprint !== schemaFingerprint
+    ) {
+      const error = new Error(
+        `Derived event contract conflict for ${eventName}@${contractVersion}`,
+      );
+      error.code = 'DERIVED_CONTRACT_SCHEMA_CONFLICT';
+      error.details = {
+        eventName,
+        contractVersion,
+        existingFingerprint: existing.schemaFingerprint,
+        rejectedFingerprint: schemaFingerprint,
+      };
+      throw error;
+    }
+    return {
+      payloadSchema: canonicalSchema,
+      schemaFingerprint,
+      existing,
+    };
+  }
+
+  async registerProducer({
+    eventName,
+    contractVersion,
+    payloadSchema,
+    producer,
+  }) {
+    const canonicalSchema = canonicalize(payloadSchema ?? {});
+    const schemaFingerprint = await this.fingerprint(canonicalSchema);
+    const existing = this.get(eventName, contractVersion);
+
+    if (
+      existing &&
+      existing.schemaFingerprint !== schemaFingerprint
+    ) {
+      await this.audit?.({
+        kind: 'derived_contract.conflict',
+        entityType: 'derived_contract',
+        entityId: `${eventName}@${contractVersion}`,
+        traceId: `derived-contract:${eventName}@${contractVersion}`,
+        details: {
+          eventName,
+          contractVersion,
+          existingFingerprint: existing.schemaFingerprint,
+          rejectedFingerprint: schemaFingerprint,
+          producer,
+        },
+      });
+
+      const error = new Error(
+        `Derived event contract conflict for ${eventName}@${contractVersion}`,
+      );
+      error.code = 'DERIVED_CONTRACT_SCHEMA_CONFLICT';
+      error.details = {
+        eventName,
+        contractVersion,
+        existingFingerprint: existing.schemaFingerprint,
+        rejectedFingerprint: schemaFingerprint,
+      };
+      throw error;
+    }
+
+    const producers = existing
+      ? [...existing.producers]
+      : [];
+    if (!producers.some((candidate) => sameProducer(candidate, producer))) {
+      producers.push({
+        triggerId: String(producer.triggerId),
+        triggerVersion: String(producer.triggerVersion),
+      });
+    }
+
+    const record = await this.store.putDerivedContract({
+      eventName,
+      contractVersion,
+      payloadSchema: canonicalSchema,
+      schemaFingerprint,
+      producers,
+    });
+
+    await this.audit?.({
+      kind: existing
+        ? 'derived_contract.producer_registered'
+        : 'derived_contract.created',
+      entityType: 'derived_contract',
+      entityId: `${eventName}@${contractVersion}`,
+      traceId: `derived-contract:${eventName}@${contractVersion}`,
+      details: {
+        eventName,
+        contractVersion,
+        schemaFingerprint,
+        producer,
+        producerCount: record.producers.length,
+      },
+    });
+
+    return {
+      status: existing ? 'producer_registered' : 'created',
+      record,
+    };
+  }
+
+  resolveConsumer({
+    eventName,
+    contractVersion,
+  }) {
+    const contracts = this.list(eventName);
+
+    if (contractVersion) {
+      const contract = contracts.find(
+        (candidate) =>
+          candidate.contractVersion === String(contractVersion),
+      );
+      if (!contract) {
+        const error = new Error(
+          `Unknown derived event contract ${eventName}@${contractVersion}`,
+        );
+        error.code = 'DERIVED_CONTRACT_NOT_FOUND';
+        throw error;
+      }
+      return contract;
+    }
+
+    if (contracts.length === 1) {
+      return contracts[0];
+    }
+
+    if (contracts.length === 0) {
+      const error = new Error(
+        `No derived event contract registered for ${eventName}`,
+      );
+      error.code = 'DERIVED_CONTRACT_NOT_FOUND';
+      throw error;
+    }
+
+    const error = new Error(
+      `Derived event consumer is ambiguous for ${eventName}; explicit contractVersion required`,
+    );
+    error.code = 'DERIVED_CONTRACT_AMBIGUOUS';
+    error.details = {
+      eventName,
+      availableVersions: contracts.map(
+        (contract) => contract.contractVersion,
+      ),
+    };
+    throw error;
+  }
+}