@semiont/event-sourcing 0.4.13 → 0.4.15

package/dist/index.js

@@ -4,7 +4,7 @@ import * as path from 'path';
 import path__default from 'path';
 import * as readline from 'readline';
 import { v4 } from 'uuid';
-import { resourceId, isSystemEvent, isResourceEvent, didToAgent, findBodyItem } from '@semiont/core';
+import { resourceId, didToAgent, findBodyItem } from '@semiont/core';
 import { createHash } from 'crypto';
 import { nanoid } from 'nanoid';
 
@@ -124,8 +124,12 @@ var EventStorage = class {
   /**
    * Append an event - handles EVERYTHING for event creation
    * Creates ID, timestamp, metadata, checksum, sequence tracking, and writes to disk
+   *
+   * @param options.correlationId - Optional id propagated from a command. Stored
+   *   on the event's metadata so subscribers (notably the events-stream → frontend
+   *   path) can match command-result events back to the POST that initiated them.
    */
-  async appendEvent(event, resourceId) {
+  async appendEvent(event, resourceId, options) {
     if (this.getSequenceNumber(resourceId) === 0) {
       await this.initializeResourceStream(resourceId);
     }
@@ -140,12 +144,12 @@ var EventStorage = class {
       sequenceNumber,
       streamPosition: 0,
       // Will be set during write
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       prevEventHash: prevEventHash || void 0,
-      checksum: sha256(completeEvent)
+      checksum: sha256(completeEvent),
+      ...options?.correlationId !== void 0 && { correlationId: options.correlationId }
     };
     const storedEvent = {
-      event: completeEvent,
+      ...completeEvent,
       metadata
     };
     await this.writeEvent(storedEvent, resourceId);
@@ -221,8 +225,12 @@ var EventStorage = class {
         const trimmed = line.trim();
         if (trimmed === "") continue;
         try {
-          const event = JSON.parse(trimmed);
-          events.push(event);
+          const parsed = JSON.parse(trimmed);
+          if ("event" in parsed && "metadata" in parsed && !("type" in parsed)) {
+            events.push({ ...parsed.event, metadata: parsed.metadata, signature: parsed.signature });
+          } else {
+            events.push(parsed);
+          }
         } catch (parseError) {
           this.logger?.error("[EventStorage] Failed to parse event", { filePath, error: parseError });
         }
@@ -369,10 +377,11 @@ var EventLog = class {
    * Append event to log
    * @param event - Resource event (from @semiont/core)
    * @param resourceId - Branded ResourceId (from @semiont/core)
+   * @param options.correlationId - Optional command correlation id (stored on metadata)
    * @returns Stored event with metadata (sequence number, timestamp, checksum)
    */
-  async append(event, resourceId) {
-    return this.storage.appendEvent(event, resourceId);
+  async append(event, resourceId, options) {
+    return this.storage.appendEvent(event, resourceId, options);
   }
   /**
    * Get all events for a resource
@@ -397,224 +406,15 @@ var EventLog = class {
     const events = await this.storage.getAllEvents(resourceId);
     if (!filter) return events;
     return events.filter((e) => {
-      if (filter.eventTypes && !filter.eventTypes.includes(e.event.type)) return false;
+      if (filter.eventTypes && !filter.eventTypes.includes(e.type)) return false;
       if (filter.fromSequence && e.metadata.sequenceNumber < filter.fromSequence) return false;
-      if (filter.fromTimestamp && e.event.timestamp < filter.fromTimestamp) return false;
-      if (filter.toTimestamp && e.event.timestamp > filter.toTimestamp) return false;
-      if (filter.userId && e.event.userId !== filter.userId) return false;
+      if (filter.fromTimestamp && e.timestamp < filter.fromTimestamp) return false;
+      if (filter.toTimestamp && e.timestamp > filter.toTimestamp) return false;
+      if (filter.userId && e.userId !== filter.userId) return false;
       return true;
     });
   }
 };
-
-// src/subscriptions/event-subscriptions.ts
-var EventSubscriptions = class {
-  // Per-resource subscriptions: ResourceId -> Set of callbacks
-  subscriptions = /* @__PURE__ */ new Map();
-  // Global subscriptions for system-level events (no resourceId)
-  globalSubscriptions = /* @__PURE__ */ new Set();
-  logger;
-  constructor(logger) {
-    this.logger = logger;
-  }
-  /**
-   * Subscribe to events for a specific resource
-   * Returns an EventSubscription with unsubscribe function
-   */
-  subscribe(resourceId, callback) {
-    if (!this.subscriptions.has(resourceId)) {
-      this.subscriptions.set(resourceId, /* @__PURE__ */ new Set());
-    }
-    const callbacks = this.subscriptions.get(resourceId);
-    callbacks.add(callback);
-    this.logger?.info("[EventSubscriptions] Subscription added for resource", { resourceId, totalSubscribers: callbacks.size });
-    return {
-      resourceId,
-      callback,
-      unsubscribe: () => {
-        callbacks.delete(callback);
-        this.logger?.info("[EventSubscriptions] Subscription removed for resource", { resourceId, remainingSubscribers: callbacks.size });
-        if (callbacks.size === 0) {
-          this.subscriptions.delete(resourceId);
-          this.logger?.info("[EventSubscriptions] No more subscribers for resource, removed from subscriptions map", { resourceId });
-        }
-      }
-    };
-  }
-  /**
-   * Subscribe to all system-level events (no resourceId)
-   * Returns an EventSubscription with unsubscribe function
-   *
-   * Use this for consumers that need to react to global events like:
-   * - entitytype.added (global entity type collection changes)
-   * - Future system-level events (user.created, workspace.created, etc.)
-   */
-  subscribeGlobal(callback) {
-    this.globalSubscriptions.add(callback);
-    this.logger?.info("[EventSubscriptions] Global subscription added", { totalSubscribers: this.globalSubscriptions.size });
-    return {
-      resourceId: "__global__",
-      // Special marker for global subscriptions
-      callback,
-      unsubscribe: () => {
-        this.globalSubscriptions.delete(callback);
-        this.logger?.info("[EventSubscriptions] Global subscription removed", { remainingSubscribers: this.globalSubscriptions.size });
-      }
-    };
-  }
-  /**
-   * Notify all subscribers for a resource when a new event is appended
-   * @param resourceId - Bare resource ID
-   */
-  async notifySubscribers(resourceId, event) {
-    const callbacks = this.subscriptions.get(resourceId);
-    if (!callbacks || callbacks.size === 0) {
-      this.logger?.info("[EventSubscriptions] Event - no subscribers to notify", { eventType: event.event.type, resourceId });
-      return;
-    }
-    this.logger?.info("[EventSubscriptions] Notifying subscribers of event", { subscriberCount: callbacks.size, eventType: event.event.type, resourceId });
-    Array.from(callbacks).forEach((callback, index) => {
-      Promise.resolve(callback(event)).then(() => {
-        this.logger?.info("[EventSubscriptions] Subscriber successfully notified", { subscriberIndex: index + 1, eventType: event.event.type });
-      }).catch((error) => {
-        this.logger?.error("[EventSubscriptions] Error in subscriber", { subscriberIndex: index + 1, resourceId, eventType: event.event.type, error });
-      });
-    });
-  }
-  /**
-   * Notify all global subscribers when a system-level event is appended
-   */
-  async notifyGlobalSubscribers(event) {
-    if (this.globalSubscriptions.size === 0) {
-      this.logger?.info("[EventSubscriptions] System event - no global subscribers to notify", { eventType: event.event.type });
-      return;
-    }
-    this.logger?.info("[EventSubscriptions] Notifying global subscribers of system event", { subscriberCount: this.globalSubscriptions.size, eventType: event.event.type });
-    Array.from(this.globalSubscriptions).forEach((callback, index) => {
-      Promise.resolve(callback(event)).then(() => {
-        this.logger?.info("[EventSubscriptions] Global subscriber successfully notified", { subscriberIndex: index + 1, eventType: event.event.type });
-      }).catch((error) => {
-        this.logger?.error("[EventSubscriptions] Error in global subscriber", { subscriberIndex: index + 1, eventType: event.event.type, error });
-      });
-    });
-  }
-  /**
-   * Get subscription count for a resource (useful for debugging)
-   */
-  getSubscriptionCount(resourceId) {
-    return this.subscriptions.get(resourceId)?.size || 0;
-  }
-  /**
-   * Get total number of active subscriptions across all resources
-   */
-  getTotalSubscriptions() {
-    let total = 0;
-    for (const callbacks of this.subscriptions.values()) {
-      total += callbacks.size;
-    }
-    return total;
-  }
-  /**
-   * Get total number of global subscriptions
-   */
-  getGlobalSubscriptionCount() {
-    return this.globalSubscriptions.size;
-  }
-};
-var globalEventSubscriptions = null;
-function getEventSubscriptions(logger) {
-  if (!globalEventSubscriptions) {
-    globalEventSubscriptions = new EventSubscriptions(logger);
-    logger?.info("[EventSubscriptions] Created global singleton instance");
-  }
-  return globalEventSubscriptions;
-}
-
-// src/event-bus.ts
-var EventBus = class {
-  // Expose subscriptions for direct access
-  subscriptions;
-  logger;
-  constructor(logger) {
-    this.logger = logger;
-    this.subscriptions = getEventSubscriptions(logger?.child({ component: "EventSubscriptions" }));
-  }
-  /**
-   * Publish event to subscribers
-   * - Resource events: notifies BOTH resource-scoped AND global subscribers
-   * - System events: notifies global subscribers only
-   * @param event - Stored event (from @semiont/core)
-   */
-  async publish(event) {
-    if (isSystemEvent(event.event)) {
-      await this.subscriptions.notifyGlobalSubscribers(event);
-    } else if (isResourceEvent(event.event)) {
-      const rid = resourceId(event.event.resourceId);
-      await this.subscriptions.notifySubscribers(rid, event);
-      await this.subscriptions.notifyGlobalSubscribers(event);
-    } else {
-      this.logger?.warn("[EventBus] Event is neither resource nor system event", { eventType: event.event.type });
-    }
-  }
-  /**
-   * Subscribe to events for a specific resource
-   * @param resourceId - Branded ResourceId (from @semiont/core)
-   * @param callback - Event callback function
-   * @returns EventSubscription with unsubscribe function
-   */
-  subscribe(resourceId, callback) {
-    return this.subscriptions.subscribe(resourceId, callback);
-  }
-  /**
-   * Subscribe to all system-level events
-   * @param callback - Event callback function
-   * @returns EventSubscription with unsubscribe function
-   */
-  subscribeGlobal(callback) {
-    return this.subscriptions.subscribeGlobal(callback);
-  }
-  /**
-   * Unsubscribe from resource events
-   * @param resourceId - Branded ResourceId (from @semiont/core)
-   * @param callback - Event callback function to remove
-   */
-  unsubscribe(resourceId, callback) {
-    const callbacks = this.subscriptions.subscriptions.get(resourceId);
-    if (callbacks) {
-      callbacks.delete(callback);
-      if (callbacks.size === 0) {
-        this.subscriptions.subscriptions.delete(resourceId);
-      }
-    }
-  }
-  /**
-   * Unsubscribe from global events
-   * @param callback - Event callback function to remove
-   */
-  unsubscribeGlobal(callback) {
-    this.subscriptions.globalSubscriptions.delete(callback);
-  }
-  /**
-   * Get subscriber count for a resource
-   * @param resourceId - Branded ResourceId (from @semiont/core)
-   * @returns Number of active subscribers
-   */
-  getSubscriberCount(resourceId) {
-    return this.subscriptions.getSubscriptionCount(resourceId);
-  }
-  /**
-   * Get total number of active subscriptions across all resources
-   */
-  getTotalSubscriptions() {
-    return this.subscriptions.getTotalSubscriptions();
-  }
-  /**
-   * Get total number of global subscriptions
-   */
-  getGlobalSubscriptionCount() {
-    return this.subscriptions.getGlobalSubscriptionCount();
-  }
-};
 var ResourceNotFoundError = class extends Error {
   constructor(uri) {
     super(`No resource found for URI: ${uri}`);
@@ -704,14 +504,14 @@ var ViewMaterializer = class {
   /**
    * Update the storage-uri index in response to an event.
    *
-   * Only resource.created (with storageUri), resource.moved, need index changes.
+   * Only yield:created (with storageUri), yield:moved, need index changes.
    * resource.archived / resource.unarchived do NOT modify the index.
    */
   async materializeStorageUriIndex(resourceId, event) {
     const projectionsDir = path.join(this.config.basePath, "projections");
-    if (event.type === "resource.created" && event.payload.storageUri) {
+    if (event.type === "yield:created" && event.payload.storageUri) {
       await writeStorageUriEntry(projectionsDir, event.payload.storageUri, resourceId);
-    } else if (event.type === "resource.moved") {
+    } else if (event.type === "yield:moved") {
       await removeStorageUriEntry(projectionsDir, event.payload.fromUri);
       await writeStorageUriEntry(projectionsDir, event.payload.toUri, resourceId);
     }
@@ -737,10 +537,10 @@ var ViewMaterializer = class {
     };
     events.sort((a, b) => a.metadata.sequenceNumber - b.metadata.sequenceNumber);
     for (const storedEvent of events) {
-      this.applyEventToResource(resource, storedEvent.event);
-      this.applyEventToAnnotations(annotations, storedEvent.event);
+      this.applyEventToResource(resource, storedEvent);
+      this.applyEventToAnnotations(annotations, storedEvent);
       annotations.version++;
-      annotations.updatedAt = storedEvent.event.timestamp;
+      annotations.updatedAt = storedEvent.timestamp;
     }
     return { resource, annotations };
   }
@@ -749,7 +549,7 @@ var ViewMaterializer = class {
    */
   applyEventToResource(resource, event) {
     switch (event.type) {
-      case "resource.created":
+      case "yield:created":
         resource.name = event.payload.name;
         resource.entityTypes = event.payload.entityTypes || [];
         resource.dateCreated = event.timestamp;
@@ -773,7 +573,7 @@ var ViewMaterializer = class {
         }
         resource.currentChecksum = event.payload.contentChecksum;
         break;
-      case "resource.cloned":
+      case "yield:cloned":
         resource.name = event.payload.name;
         resource.entityTypes = event.payload.entityTypes || [];
         resource.dateCreated = event.timestamp;
@@ -791,21 +591,21 @@ var ViewMaterializer = class {
         });
         resource.representations = reps2;
         break;
-      case "resource.updated":
+      case "yield:updated":
         resource.currentChecksum = event.payload.contentChecksum;
         resource.dateModified = event.timestamp;
         break;
-      case "resource.moved":
+      case "yield:moved":
         resource.storageUri = event.payload.toUri;
         resource.dateModified = event.timestamp;
         break;
-      case "resource.archived":
+      case "mark:archived":
         resource.archived = true;
         break;
-      case "resource.unarchived":
+      case "mark:unarchived":
         resource.archived = false;
         break;
-      case "representation.added": {
+      case "yield:representation-added": {
         const { representation } = event.payload;
         if (!resource.representations) {
           resource.representations = [];
@@ -817,7 +617,7 @@ var ViewMaterializer = class {
         }
         break;
       }
-      case "representation.removed": {
+      case "yield:representation-removed": {
         const { checksum } = event.payload;
         if (resource.representations) {
           const repsArray = Array.isArray(resource.representations) ? resource.representations : [resource.representations];
@@ -825,13 +625,13 @@ var ViewMaterializer = class {
         }
         break;
       }
-      case "entitytag.added":
+      case "mark:entity-tag-added":
         if (!resource.entityTypes) resource.entityTypes = [];
         if (!resource.entityTypes.includes(event.payload.entityType)) {
           resource.entityTypes.push(event.payload.entityType);
         }
         break;
-      case "entitytag.removed":
+      case "mark:entity-tag-removed":
         if (resource.entityTypes) {
           resource.entityTypes = resource.entityTypes.filter(
             (t) => t !== event.payload.entityType
@@ -845,15 +645,15 @@ var ViewMaterializer = class {
    */
   applyEventToAnnotations(annotations, event) {
     switch (event.type) {
-      case "annotation.added":
+      case "mark:added":
         annotations.annotations.push(event.payload.annotation);
         break;
-      case "annotation.removed":
+      case "mark:removed":
         annotations.annotations = annotations.annotations.filter(
           (a) => a.id !== event.payload.annotationId
         );
         break;
-      case "annotation.body.updated":
+      case "mark:body-updated":
         const annotation = annotations.annotations.find(
           (a) => a.id === event.payload.annotationId
         );
@@ -884,6 +684,44 @@ var ViewMaterializer = class {
         break;
     }
   }
+  /**
+   * Walk every event stream in the event log and materialize the corresponding
+   * view from scratch. Idempotent: existing view files are overwritten.
+   *
+   * Mirrors GraphDBConsumer.rebuildAll() and Smelter.rebuildAll() — this is the
+   * recovery path that makes the ephemeral stateDir safe to wipe. The live
+   * append path (EventStore.appendEvent → materializeIncremental /
+   * materializeEntityTypes) is unchanged and runs in addition.
+   */
+  async rebuildAll(eventLog) {
+    this.logger?.info("[ViewMaterializer] Rebuilding all materialized views from event log");
+    const SYSTEM_ID = "__system__";
+    const systemEvents = await eventLog.getEvents(SYSTEM_ID);
+    this.logger?.info("[ViewMaterializer] Replaying system events", { count: systemEvents.length });
+    for (const event of systemEvents) {
+      if (event.type === "mark:entity-type-added") {
+        await this.materializeEntityTypes(event.payload.entityType);
+      }
+    }
+    const allResourceIds = await eventLog.getAllResourceIds();
+    const resourceIds = allResourceIds.filter(
+      (rid) => rid !== "__system__"
+    );
+    this.logger?.info("[ViewMaterializer] Rebuilding resource views", { count: resourceIds.length });
+    for (const rid of resourceIds) {
+      const events = await eventLog.getEvents(rid);
+      if (events.length === 0) continue;
+      const view = this.materializeFromEvents(events, rid);
+      await this.viewStorage.save(rid, view);
+      for (const event of events) {
+        await this.materializeStorageUriIndex(rid, event);
+      }
+    }
+    this.logger?.info("[ViewMaterializer] Rebuild complete", {
+      systemEvents: systemEvents.length,
+      resources: resourceIds.length
+    });
+  }
   /**
    * Materialize entity types view - System-level view
    */
@@ -935,10 +773,19 @@ var ViewManager = class {
    * @param payload - Event payload
    */
   async materializeSystem(eventType, payload) {
-    if (eventType === "entitytype.added") {
+    if (eventType === "mark:entity-type-added") {
       await this.materializer.materializeEntityTypes(payload.entityType);
     }
   }
+  /**
+   * Rebuild all materialized views from the event log on startup.
+   * Mirrors GraphDBConsumer.rebuildAll() — call this once during
+   * createKnowledgeBase before the HTTP server begins accepting requests.
+   * Idempotent: existing view files are overwritten.
+   */
+  async rebuildAll(eventLog) {
+    return this.materializer.rebuildAll(eventLog);
+  }
   /**
    * Get resource view (builds from events if needed)
    * @param resourceId - Branded ResourceId (from @semiont/core)
@@ -954,7 +801,6 @@ var ViewManager = class {
 var EventStore = class {
   // Focused components - each with single responsibility
   log;
-  bus;
   views;
   viewStorage;
   coreEventBus;
@@ -962,7 +808,6 @@ var EventStore = class {
     this.viewStorage = viewStorage;
     this.coreEventBus = coreEventBus;
     this.log = new EventLog({ project }, logger?.child({ component: "EventLog" }));
-    this.bus = new EventBus(logger?.child({ component: "EventBus" }));
     const viewConfig = {
       basePath: stateDir
     };
@@ -971,28 +816,31 @@ var EventStore = class {
   /**
    * Append an event to the store
    * Coordinates: persistence → view → notification
+   *
+   * @param options.correlationId - Optional id propagated from a command. Stored
+   *   on the event's metadata so that subscribers (notably the events-stream
+   *   route) can match command-result events back to the POST that initiated
+   *   them. Pass through from your route handler when handling commands.
    */
-  async appendEvent(event) {
+  async appendEvent(event, options) {
     const resourceId = event.resourceId || "__system__";
-    const storedEvent = await this.log.append(event, resourceId);
+    const storedEvent = await this.log.append(event, resourceId, options);
     if (resourceId === "__system__") {
       await this.views.materializeSystem(
-        storedEvent.event.type,
-        storedEvent.event.payload
+        storedEvent.type,
+        storedEvent.payload
       );
     } else {
       await this.views.materializeResource(
         resourceId,
-        storedEvent.event,
+        storedEvent,
         () => this.log.getEvents(resourceId)
       );
     }
-    await this.bus.publish(storedEvent);
-    if (this.coreEventBus && resourceId !== "__system__") {
+    this.coreEventBus.getDomainEvent(storedEvent.type).next(storedEvent);
+    if (resourceId !== "__system__") {
       const scopedBus = this.coreEventBus.scope(resourceId);
-      const eventChannel = storedEvent.event.type.replace(/\./g, ":");
-      scopedBus.get(eventChannel).next(storedEvent.event);
-      scopedBus.get("make-meaning:event").next(storedEvent.event);
+      scopedBus.getDomainEvent(storedEvent.type).next(storedEvent);
     }
     return storedEvent;
   }
@@ -1115,16 +963,16 @@ var EventQuery = class {
     const allEvents = await this.eventStorage.getAllEvents(query.resourceId);
     let results = allEvents;
     if (query.userId) {
-      results = results.filter((e) => e.event.userId === query.userId);
+      results = results.filter((e) => e.userId === query.userId);
     }
     if (query.eventTypes && query.eventTypes.length > 0) {
-      results = results.filter((e) => query.eventTypes.includes(e.event.type));
+      results = results.filter((e) => query.eventTypes.includes(e.type));
     }
     if (query.fromTimestamp) {
-      results = results.filter((e) => e.event.timestamp >= query.fromTimestamp);
+      results = results.filter((e) => e.timestamp >= query.fromTimestamp);
     }
     if (query.toTimestamp) {
-      results = results.filter((e) => e.event.timestamp <= query.toTimestamp);
+      results = results.filter((e) => e.timestamp <= query.toTimestamp);
     }
     if (query.fromSequence) {
       results = results.filter((e) => e.metadata.sequenceNumber >= query.fromSequence);
@@ -1178,6 +1026,10 @@ var EventQuery = class {
 };
 
 // src/validation/event-validator.ts
+function extractPersistedEvent(stored) {
+  const { metadata, signature, ...event } = stored;
+  return event;
+}
 var EventValidator = class {
   /**
    * Validate event chain integrity for a resource's events
@@ -1194,7 +1046,7 @@ var EventValidator = class {
           `Event chain broken at sequence ${curr.metadata.sequenceNumber}: prevEventHash=${curr.metadata.prevEventHash} but previous checksum=${prev.metadata.checksum}`
         );
       }
-      const calculated = sha256(curr.event);
+      const calculated = sha256(extractPersistedEvent(curr));
       if (calculated !== curr.metadata.checksum) {
         errors.push(
           `Checksum mismatch at sequence ${curr.metadata.sequenceNumber}: calculated=${calculated} but stored=${curr.metadata.checksum}`
@@ -1211,7 +1063,7 @@ var EventValidator = class {
    * Useful for validating events before writing them
    */
   validateEventChecksum(event) {
-    const calculated = sha256(event.event);
+    const calculated = sha256(extractPersistedEvent(event));
     return calculated === event.metadata.checksum;
   }
   /**
@@ -1229,6 +1081,6 @@ function generateAnnotationId() {
   return nanoid(21);
 }
 
-export { EventBus, EventLog, EventQuery, EventStorage, EventStore, EventSubscriptions, EventValidator, FilesystemViewStorage, ResourceNotFoundError, ViewManager, ViewMaterializer, createEventStore, generateAnnotationId, getEventSubscriptions, getShardPath, jumpConsistentHash, removeStorageUriEntry, resolveStorageUri, sha256, writeStorageUriEntry };
+export { EventLog, EventQuery, EventStorage, EventStore, EventValidator, FilesystemViewStorage, ResourceNotFoundError, ViewManager, ViewMaterializer, createEventStore, generateAnnotationId, getShardPath, jumpConsistentHash, removeStorageUriEntry, resolveStorageUri, sha256, writeStorageUriEntry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map