mcp-event-intelligence 0.1.0

package/dist/src/composite/temporal.js

@@ -0,0 +1,317 @@
+function getByPath(source, path) {
+    let current = source;
+    for (const part of path.split('.')) {
+        if (current === null ||
+            typeof current !== 'object' ||
+            Array.isArray(current))
+            return undefined;
+        current = current[part];
+    }
+    return current;
+}
+function eventsFor(record, ref) {
+    return record.sourceEvents
+        .filter((event) => event.clauseId === ref)
+        .sort((a, b) => Date.parse(a.occurredAt) - Date.parse(b.occurredAt));
+}
+function latestEvent(record, ref) {
+    return eventsFor(record, ref).at(-1) ?? null;
+}
+function parseClock(value) {
+    const [hour, minute] = value.split(':').map(Number);
+    return hour * 60 + minute;
+}
+const WEEKDAY_TO_ISO = {
+    Mon: 1,
+    Tue: 2,
+    Wed: 3,
+    Thu: 4,
+    Fri: 5,
+    Sat: 6,
+    Sun: 7,
+};
+export function zonedParts(timestamp, timeZone) {
+    const date = timestamp instanceof Date ? timestamp : new Date(timestamp);
+    const formatter = new Intl.DateTimeFormat('en-CA', {
+        timeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hourCycle: 'h23',
+        weekday: 'short',
+    });
+    const raw = Object.fromEntries(formatter.formatToParts(date).map((part) => [part.type, part.value]));
+    const year = Number(raw.year);
+    const month = Number(raw.month);
+    const day = Number(raw.day);
+    return {
+        year,
+        month,
+        day,
+        hour: Number(raw.hour),
+        minute: Number(raw.minute),
+        second: Number(raw.second),
+        weekday: WEEKDAY_TO_ISO[String(raw.weekday)],
+        date: `${String(year).padStart(4, '0')}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`,
+    };
+}
+export function localDateTimeToUtc(date, clock, timeZone) {
+    const [hour, minute] = clock.split(':').map(Number);
+    const desiredAsUtc = Date.UTC(date.year, date.month - 1, date.day, hour, minute, 0, 0);
+    let guess = desiredAsUtc;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        const actual = zonedParts(new Date(guess), timeZone);
+        const actualAsUtc = Date.UTC(actual.year, actual.month - 1, actual.day, actual.hour, actual.minute, actual.second, 0);
+        const delta = desiredAsUtc - actualAsUtc;
+        if (delta === 0)
+            break;
+        guess += delta;
+    }
+    return new Date(guess);
+}
+function calendarMatches(condition, event) {
+    const parts = zonedParts(event.occurredAt, condition.timezone);
+    const minutes = parts.hour * 60 + parts.minute;
+    if (condition.weekdays && !condition.weekdays.includes(parts.weekday)) {
+        return false;
+    }
+    if (condition.dates && !condition.dates.includes(parts.date)) {
+        return false;
+    }
+    if (condition.dateRange &&
+        (parts.date < condition.dateRange.start ||
+            parts.date > condition.dateRange.end)) {
+        return false;
+    }
+    if (condition.dayOfMonth &&
+        !condition.dayOfMonth.includes(parts.day)) {
+        return false;
+    }
+    if (condition.before && condition.after) {
+        const before = parseClock(condition.before);
+        const after = parseClock(condition.after);
+        if (after <= before) {
+            if (minutes < after || minutes > before)
+                return false;
+        }
+        else {
+            if (!(minutes >= after || minutes <= before))
+                return false;
+        }
+    }
+    else {
+        if (condition.before && minutes > parseClock(condition.before)) {
+            return false;
+        }
+        if (condition.after && minutes < parseClock(condition.after)) {
+            return false;
+        }
+    }
+    return true;
+}
+function absenceDueAt(condition, anchor) {
+    const anchorMs = Date.parse(anchor.occurredAt);
+    if (condition.forMs) {
+        return new Date(anchorMs + condition.forMs);
+    }
+    const zone = condition.timezone;
+    const parts = zonedParts(anchor.occurredAt, zone);
+    const due = localDateTimeToUtc(parts, condition.untilLocalTime, zone);
+    return due.getTime() < anchorMs ? new Date(anchorMs) : due;
+}
+function state(condition, status, extra = {}) {
+    return {
+        conditionId: condition.id,
+        kind: condition.kind,
+        status,
+        ...extra,
+    };
+}
+export function evaluateTemporalConditions(definition, record, now) {
+    const states = [];
+    const pendingDeadlines = [];
+    for (const condition of definition.temporal ?? []) {
+        if (condition.kind === 'calendar') {
+            const event = latestEvent(record, condition.ref);
+            if (!event) {
+                states.push(state(condition, 'pending', {
+                    reason: 'referenced event has not occurred',
+                }));
+                continue;
+            }
+            states.push(calendarMatches(condition, event)
+                ? state(condition, 'satisfied')
+                : state(condition, 'blocked', {
+                    reason: 'event is outside the configured calendar window',
+                }));
+            continue;
+        }
+        if (condition.kind === 'not' || condition.kind === 'unless') {
+            const exists = eventsFor(record, condition.ref).length > 0;
+            states.push(exists
+                ? state(condition, 'blocked', {
+                    reason: `${condition.ref} occurred`,
+                })
+                : state(condition, 'satisfied'));
+            continue;
+        }
+        if (condition.kind === 'after') {
+            const event = latestEvent(record, condition.ref);
+            const anchor = latestEvent(record, condition.afterRef);
+            if (!event || !anchor) {
+                states.push(state(condition, 'pending', {
+                    reason: 'ordering events are incomplete',
+                }));
+            }
+            else if (Date.parse(event.occurredAt) > Date.parse(anchor.occurredAt)) {
+                states.push(state(condition, 'satisfied'));
+            }
+            else {
+                states.push(state(condition, 'blocked', {
+                    reason: `${condition.ref} did not occur after ${condition.afterRef}`,
+                }));
+            }
+            continue;
+        }
+        if (condition.kind === 'until') {
+            const event = latestEvent(record, condition.ref);
+            const boundary = latestEvent(record, condition.beforeRef);
+            if (!event || !boundary) {
+                states.push(state(condition, 'pending', {
+                    reason: 'ordering events are incomplete',
+                }));
+            }
+            else if (Date.parse(event.occurredAt) <= Date.parse(boundary.occurredAt)) {
+                states.push(state(condition, 'satisfied'));
+            }
+            else {
+                states.push(state(condition, 'blocked', {
+                    reason: `${condition.ref} occurred after ${condition.beforeRef}`,
+                }));
+            }
+            continue;
+        }
+        if (condition.kind === 'threshold') {
+            const count = eventsFor(record, condition.ref).length;
+            states.push(count >= condition.atLeast
+                ? state(condition, 'satisfied')
+                : state(condition, 'pending', {
+                    reason: `${count}/${condition.atLeast} occurrences`,
+                }));
+            continue;
+        }
+        if (condition.kind === 'distinct') {
+            const values = new Set(eventsFor(record, condition.ref)
+                .map((event) => getByPath(event.data, condition.path))
+                .filter((value) => typeof value === 'string' ||
+                typeof value === 'number' ||
+                typeof value === 'boolean')
+                .map(String));
+            states.push(values.size >= condition.atLeast
+                ? state(condition, 'satisfied')
+                : state(condition, 'pending', {
+                    reason: `${values.size}/${condition.atLeast} distinct values`,
+                }));
+            continue;
+        }
+        if (condition.kind === 'rate') {
+            const events = eventsFor(record, condition.ref);
+            if (!events.length) {
+                states.push(state(condition, 'pending', {
+                    reason: 'no events in rate window',
+                }));
+                continue;
+            }
+            const end = Math.max(now.getTime(), Date.parse(events.at(-1).occurredAt));
+            const count = events.filter((event) => end - Date.parse(event.occurredAt) <= condition.perMs).length;
+            states.push(count >= condition.atLeast
+                ? state(condition, 'satisfied')
+                : state(condition, 'pending', {
+                    reason: `${count}/${condition.atLeast} occurrences in rate window`,
+                }));
+            continue;
+        }
+        if (condition.kind === 'debounce') {
+            const event = latestEvent(record, condition.ref);
+            if (!event) {
+                states.push(state(condition, 'pending', {
+                    reason: 'debounced event has not occurred',
+                }));
+                continue;
+            }
+            const dueAt = new Date(Date.parse(event.occurredAt) + condition.forMs).toISOString();
+            if (now.getTime() >= Date.parse(dueAt)) {
+                states.push(state(condition, 'satisfied', { dueAt }));
+            }
+            else {
+                states.push(state(condition, 'pending', {
+                    dueAt,
+                    reason: 'waiting for quiet period',
+                }));
+                pendingDeadlines.push({
+                    conditionId: condition.id,
+                    dueAt,
+                });
+            }
+            continue;
+        }
+        if (condition.kind === 'absence') {
+            const anchor = latestEvent(record, condition.afterRef);
+            if (!anchor) {
+                states.push(state(condition, 'pending', {
+                    reason: `waiting for anchor ${condition.afterRef}`,
+                }));
+                continue;
+            }
+            const due = absenceDueAt(condition, anchor);
+            const dueAt = due.toISOString();
+            const anchorMs = Date.parse(anchor.occurredAt);
+            const disqualifying = eventsFor(record, condition.ref)
+                .some((event) => {
+                const at = Date.parse(event.occurredAt);
+                return at >= anchorMs && at <= due.getTime();
+            });
+            if (disqualifying) {
+                states.push(state(condition, 'blocked', {
+                    dueAt,
+                    reason: `${condition.ref} occurred before the absence deadline`,
+                }));
+            }
+            else if (now.getTime() >= due.getTime()) {
+                states.push(state(condition, 'satisfied', { dueAt }));
+            }
+            else {
+                states.push(state(condition, 'pending', {
+                    dueAt,
+                    reason: 'absence window is still open',
+                }));
+                pendingDeadlines.push({
+                    conditionId: condition.id,
+                    dueAt,
+                });
+            }
+        }
+    }
+    if (states.some((entry) => entry.status === 'blocked')) {
+        return {
+            outcome: 'blocked',
+            pendingDeadlines,
+            conditionStates: states,
+        };
+    }
+    if (states.some((entry) => entry.status === 'pending')) {
+        return {
+            outcome: 'pending',
+            pendingDeadlines,
+            conditionStates: states,
+        };
+    }
+    return {
+        outcome: 'satisfied',
+        pendingDeadlines,
+        conditionStates: states,
+    };
+}

package/dist/src/intelligenceProtocol/audit.d.ts

@@ -0,0 +1,19 @@
+import { type AuditRecord, type LifecycleState } from './schemas.js';
+export interface AppendAuditInput {
+    auditId: string;
+    traceId: string;
+    timestamp: string;
+    kind: AuditRecord['kind'];
+    entityType: AuditRecord['entityType'];
+    entityId: string;
+    fromState?: LifecycleState | null;
+    toState?: LifecycleState | null;
+    details?: Record<string, unknown>;
+}
+export declare class AuditChain {
+    private readonly records;
+    constructor(initialRecords?: AuditRecord[]);
+    append(input: AppendAuditInput): Promise<AuditRecord>;
+    list(): AuditRecord[];
+    verify(): Promise<boolean>;
+}

package/dist/src/intelligenceProtocol/audit.js

@@ -0,0 +1,56 @@
+import { AuditRecordSchema, } from './schemas.js';
+import { canonicalJson, sha256Hex } from './canonical.js';
+import { assertTransition } from './lifecycle.js';
+export class AuditChain {
+    records;
+    constructor(initialRecords = []) {
+        this.records = initialRecords.map((record) => AuditRecordSchema.parse(record));
+    }
+    async append(input) {
+        if (input.fromState && input.toState) {
+            assertTransition(input.fromState, input.toState);
+        }
+        const previousHash = this.records.length === 0
+            ? null
+            : this.records[this.records.length - 1].hash;
+        const unsigned = {
+            auditId: input.auditId,
+            sequence: this.records.length,
+            traceId: input.traceId,
+            timestamp: input.timestamp,
+            kind: input.kind,
+            entityType: input.entityType,
+            entityId: input.entityId,
+            ...(input.fromState !== undefined ? { fromState: input.fromState } : {}),
+            ...(input.toState !== undefined ? { toState: input.toState } : {}),
+            details: input.details ?? {},
+            previousHash,
+        };
+        const hash = await sha256Hex(canonicalJson(unsigned));
+        const record = AuditRecordSchema.parse({ ...unsigned, hash });
+        this.records.push(record);
+        return record;
+    }
+    list() {
+        return this.records.map((record) => ({
+            ...record,
+            details: { ...record.details },
+        }));
+    }
+    async verify() {
+        let previousHash = null;
+        for (let index = 0; index < this.records.length; index += 1) {
+            const record = this.records[index];
+            if (record.sequence !== index)
+                return false;
+            if (record.previousHash !== previousHash)
+                return false;
+            const { hash, ...unsigned } = record;
+            const expected = await sha256Hex(canonicalJson(unsigned));
+            if (hash !== expected)
+                return false;
+            previousHash = hash;
+        }
+        return true;
+    }
+}

package/dist/src/intelligenceProtocol/canonical.d.ts

@@ -0,0 +1,2 @@
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256Hex(value: unknown): Promise<string>;

package/dist/src/intelligenceProtocol/canonical.js

@@ -0,0 +1,21 @@
+function normalize(value) {
+    if (Array.isArray(value)) {
+        return value.map(normalize);
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, item]) => [key, normalize(item)]));
+    }
+    return value;
+}
+export function canonicalJson(value) {
+    return JSON.stringify(normalize(value));
+}
+export async function sha256Hex(value) {
+    const bytes = new TextEncoder().encode(typeof value === 'string' ? value : canonicalJson(value));
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+    return [...new Uint8Array(digest)]
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+}

package/dist/src/intelligenceProtocol/index.d.ts

@@ -0,0 +1,12 @@
+export { EVENT_INTELLIGENCE_PROTOCOL, EVENT_INTELLIGENCE_PROTOCOL_VERSION, EVENT_INTELLIGENCE_SCHEMA_VERSION, EVENT_INTELLIGENCE_COMPATIBILITY, } from './version.js';
+export { RuntimeTargetSchema, EventSourceSchema, EventLineageSchema, McpEventOccurrenceSchema, SemanticConditionWireSchema, EventIngestRequestSchema, SemanticDecisionRecordSchema, WakeRecordSchema, LifecycleStateSchema, AuditKindSchema, AuditRecordSchema, parseEventIngestRequest, parseEventLineage, parseSemanticDecisionRecord, parseWakeRecord, parseAuditRecord, } from './schemas.js';
+export type { RuntimeTarget, McpEventOccurrence, SemanticConditionWire, EventIngestRequest, EventLineage, SemanticDecisionRecord, WakeRecord, LifecycleState, AuditRecord, } from './schemas.js';
+export { canTransition, assertTransition, allowedTransitions, } from './lifecycle.js';
+export { canonicalJson, sha256Hex, } from './canonical.js';
+export { AuditChain, } from './audit.js';
+export type { AppendAuditInput, } from './audit.js';
+export { mapMcpEventToLineage, } from './mapper.js';
+export type { MapMcpEventInput, } from './mapper.js';
+export { assertDecisionLineage, assertWakeLineage, } from './invariants.js';
+export { COMPOSITE_TRIGGER_PROTOCOL_VERSION, COMPOSITE_TRIGGER_SCHEMA_VERSION, StructuredPredicateSchema, TriggerClauseSchema, DerivedEventProjectionSchema, DerivedEventDefinitionSchema, DerivedEventEvidenceRefSchema, DerivedEventRecordSchema, DeterministicCorrelationSchema, SemanticCorrelationSchema, CompositeTriggerDefinitionSchema, CorrelatableEventSchema, TriggerSourceEventSchema, CompositeCorrelationDecisionSchema, TriggerMatchStatusSchema, TriggerMatchRecordSchema, parseCompositeTriggerDefinition, parseCorrelatableEvent, parseTriggerMatchRecord, parseDerivedEventRecord, } from './triggerSchemas.js';
+export type { StructuredPredicate, TriggerClause, DerivedEventDefinition, DerivedEventRecord, CompositeTriggerDefinition, CorrelatableEvent, TriggerSourceEvent, TriggerMatchRecord, CompositeCorrelationDecision, } from './triggerSchemas.js';

package/dist/src/intelligenceProtocol/index.js

@@ -0,0 +1,8 @@
+export { EVENT_INTELLIGENCE_PROTOCOL, EVENT_INTELLIGENCE_PROTOCOL_VERSION, EVENT_INTELLIGENCE_SCHEMA_VERSION, EVENT_INTELLIGENCE_COMPATIBILITY, } from './version.js';
+export { RuntimeTargetSchema, EventSourceSchema, EventLineageSchema, McpEventOccurrenceSchema, SemanticConditionWireSchema, EventIngestRequestSchema, SemanticDecisionRecordSchema, WakeRecordSchema, LifecycleStateSchema, AuditKindSchema, AuditRecordSchema, parseEventIngestRequest, parseEventLineage, parseSemanticDecisionRecord, parseWakeRecord, parseAuditRecord, } from './schemas.js';
+export { canTransition, assertTransition, allowedTransitions, } from './lifecycle.js';
+export { canonicalJson, sha256Hex, } from './canonical.js';
+export { AuditChain, } from './audit.js';
+export { mapMcpEventToLineage, } from './mapper.js';
+export { assertDecisionLineage, assertWakeLineage, } from './invariants.js';
+export { COMPOSITE_TRIGGER_PROTOCOL_VERSION, COMPOSITE_TRIGGER_SCHEMA_VERSION, StructuredPredicateSchema, TriggerClauseSchema, DerivedEventProjectionSchema, DerivedEventDefinitionSchema, DerivedEventEvidenceRefSchema, DerivedEventRecordSchema, DeterministicCorrelationSchema, SemanticCorrelationSchema, CompositeTriggerDefinitionSchema, CorrelatableEventSchema, TriggerSourceEventSchema, CompositeCorrelationDecisionSchema, TriggerMatchStatusSchema, TriggerMatchRecordSchema, parseCompositeTriggerDefinition, parseCorrelatableEvent, parseTriggerMatchRecord, parseDerivedEventRecord, } from './triggerSchemas.js';

package/dist/src/intelligenceProtocol/invariants.d.ts

@@ -0,0 +1,3 @@
+import type { EventLineage, SemanticDecisionRecord, WakeRecord } from './schemas.js';
+export declare function assertDecisionLineage(event: EventLineage, decision: SemanticDecisionRecord): void;
+export declare function assertWakeLineage(event: EventLineage, decision: SemanticDecisionRecord | null, wake: WakeRecord): void;

package/dist/src/intelligenceProtocol/invariants.js

@@ -0,0 +1,36 @@
+export function assertDecisionLineage(event, decision) {
+    if (decision.traceId !== event.traceId) {
+        throw new Error('Decision traceId does not match source event');
+    }
+    if (decision.subscriptionId !== event.subscriptionId) {
+        throw new Error('Decision subscriptionId does not match source event');
+    }
+    if (decision.sourceEventId !== event.sourceEventId) {
+        throw new Error('Decision sourceEventId does not match source event');
+    }
+}
+export function assertWakeLineage(event, decision, wake) {
+    if (wake.traceId !== event.traceId) {
+        throw new Error('Wake traceId does not match source event');
+    }
+    if (wake.subscriptionId !== event.subscriptionId) {
+        throw new Error('Wake subscriptionId does not match source event');
+    }
+    if (wake.sourceEventId !== event.sourceEventId) {
+        throw new Error('Wake sourceEventId does not match source event');
+    }
+    if (decision) {
+        assertDecisionLineage(event, decision);
+        if (wake.decisionId !== decision.decisionId) {
+            throw new Error('Wake decisionId does not match semantic decision');
+        }
+    }
+    else if (wake.decisionId !== null) {
+        throw new Error('Wake has decisionId but no decision record was supplied');
+    }
+    if (wake.target.runtime !== event.target.runtime ||
+        wake.target.kind !== event.target.kind ||
+        wake.target.id !== event.target.id) {
+        throw new Error('Wake target does not match source event target');
+    }
+}

package/dist/src/intelligenceProtocol/lifecycle.d.ts

@@ -0,0 +1,4 @@
+import type { LifecycleState } from './schemas.js';
+export declare function canTransition(from: LifecycleState, to: LifecycleState): boolean;
+export declare function assertTransition(from: LifecycleState, to: LifecycleState): void;
+export declare function allowedTransitions(from: LifecycleState): LifecycleState[];

package/dist/src/intelligenceProtocol/lifecycle.js

@@ -0,0 +1,24 @@
+const ALLOWED = {
+    received: new Set(['duplicate', 'evaluating', 'matched', 'failed']),
+    duplicate: new Set(),
+    evaluating: new Set(['matched', 'rejected', 'escalated', 'failed']),
+    matched: new Set(['wake_queued', 'failed']),
+    rejected: new Set(),
+    escalated: new Set(['wake_queued', 'rejected', 'failed']),
+    wake_queued: new Set(['wake_delivered', 'dead_letter', 'failed']),
+    wake_delivered: new Set(['handled', 'dead_letter', 'failed']),
+    handled: new Set(),
+    failed: new Set(['dead_letter']),
+    dead_letter: new Set(),
+};
+export function canTransition(from, to) {
+    return ALLOWED[from].has(to);
+}
+export function assertTransition(from, to) {
+    if (!canTransition(from, to)) {
+        throw new Error(`Invalid event-intelligence lifecycle transition: ${from} -> ${to}`);
+    }
+}
+export function allowedTransitions(from) {
+    return [...ALLOWED[from]];
+}

package/dist/src/intelligenceProtocol/mapper.d.ts

@@ -0,0 +1,14 @@
+import type { EventOccurrence } from '../protocol/types.js';
+import { type EventLineage, type RuntimeTarget } from './schemas.js';
+export interface MapMcpEventInput {
+    event: EventOccurrence;
+    traceId: string;
+    environmentId: string;
+    subscriptionId: string;
+    serverId: string;
+    transport: 'stdio' | 'streamable_http' | 'webhook' | 'poll' | 'internal';
+    provider?: string;
+    target: RuntimeTarget;
+    observedAt: string;
+}
+export declare function mapMcpEventToLineage(input: MapMcpEventInput): Promise<EventLineage>;

package/dist/src/intelligenceProtocol/mapper.js

@@ -0,0 +1,28 @@
+import { sha256Hex } from './canonical.js';
+import { EventLineageSchema, } from './schemas.js';
+import { EVENT_INTELLIGENCE_PROTOCOL, EVENT_INTELLIGENCE_PROTOCOL_VERSION, EVENT_INTELLIGENCE_SCHEMA_VERSION, } from './version.js';
+export async function mapMcpEventToLineage(input) {
+    const payloadHash = await sha256Hex(input.event.data);
+    return EventLineageSchema.parse({
+        protocol: EVENT_INTELLIGENCE_PROTOCOL,
+        protocolVersion: EVENT_INTELLIGENCE_PROTOCOL_VERSION,
+        schemaVersion: EVENT_INTELLIGENCE_SCHEMA_VERSION,
+        traceId: input.traceId,
+        environmentId: input.environmentId,
+        subscriptionId: input.subscriptionId,
+        sourceEventId: input.event.eventId,
+        observedAt: input.observedAt,
+        source: {
+            serverId: input.serverId,
+            transport: input.transport,
+            ...(input.provider ? { provider: input.provider } : {}),
+            cursor: input.event.cursor ?? null,
+        },
+        target: input.target,
+        event: {
+            name: input.event.name,
+            occurredAt: input.event.timestamp,
+            payloadHash,
+        },
+    });
+}