@semiont/event-sourcing 0.4.13 → 0.4.15

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ResourceId, components, ResourceAnnotations, Logger, ResourceEvent, StoredEvent, EventQuery as EventQuery$1, EventBus as EventBus$1 } from '@semiont/core';
+import { ResourceId, components, ResourceAnnotations, Logger, EventInput, StoredEvent, EventQuery as EventQuery$1, PersistedEvent, EventBus } from '@semiont/core';
 import { SemiontProject } from '@semiont/core/node';
 
 /**
@@ -82,8 +82,14 @@ declare class EventStorage {
     /**
      * 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.
      */
-    appendEvent(event: Omit<ResourceEvent, 'id' | 'timestamp'>, resourceId: ResourceId): Promise<StoredEvent>;
+    appendEvent(event: EventInput, resourceId: ResourceId, options?: {
+        correlationId?: string;
+    }): Promise<StoredEvent>;
     /**
      * Write an event to storage (append to JSONL)
      * Internal method - use appendEvent() instead
@@ -167,9 +173,12 @@ declare class EventLog {
      * 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)
      */
-    append(event: Omit<ResourceEvent, 'id' | 'timestamp'>, resourceId: ResourceId): Promise<StoredEvent>;
+    append(event: EventInput, resourceId: ResourceId, options?: {
+        correlationId?: string;
+    }): Promise<StoredEvent>;
     /**
      * Get all events for a resource
      * @param resourceId - Branded ResourceId (from @semiont/core)
@@ -188,141 +197,6 @@ declare class EventLog {
     queryEvents(resourceId: ResourceId, filter?: EventQuery$1): Promise<StoredEvent[]>;
 }
 
-/**
- * Event Subscriptions - Real-time Event Pub/Sub
- *
- * Manages subscriptions for both resource-scoped and system-level events:
- * - Resource subscriptions: notifications for a specific resource's events
- * - Global subscriptions: notifications for all system-level events
- * - Fire-and-forget notification pattern (non-blocking)
- * - Automatic cleanup of empty subscription sets
- *
- * SINGLETON PATTERN: All EventStore instances share the same EventSubscriptions
- * to ensure SSE connections receive events from any EventStore instance.
- *
- * @see docs/EVENT-STORE.md#eventsubscriptions for architecture details
- */
-
-type EventCallback = (event: StoredEvent) => void | Promise<void>;
-interface EventSubscription {
-    resourceId: ResourceId;
-    callback: EventCallback;
-    unsubscribe: () => void;
-}
-/**
- * EventSubscriptions manages real-time event pub/sub
- * Supports both resource-scoped and global subscriptions
- */
-declare class EventSubscriptions {
-    private subscriptions;
-    private globalSubscriptions;
-    private logger?;
-    constructor(logger?: Logger);
-    /**
-     * Subscribe to events for a specific resource
-     * Returns an EventSubscription with unsubscribe function
-     */
-    subscribe(resourceId: ResourceId, callback: EventCallback): EventSubscription;
-    /**
-     * 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: EventCallback): EventSubscription;
-    /**
-     * Notify all subscribers for a resource when a new event is appended
-     * @param resourceId - Bare resource ID
-     */
-    notifySubscribers(resourceId: ResourceId, event: StoredEvent): Promise<void>;
-    /**
-     * Notify all global subscribers when a system-level event is appended
-     */
-    notifyGlobalSubscribers(event: StoredEvent): Promise<void>;
-    /**
-     * Get subscription count for a resource (useful for debugging)
-     */
-    getSubscriptionCount(resourceId: ResourceId): number;
-    /**
-     * Get total number of active subscriptions across all resources
-     */
-    getTotalSubscriptions(): number;
-    /**
-     * Get total number of global subscriptions
-     */
-    getGlobalSubscriptionCount(): number;
-}
-declare function getEventSubscriptions(logger?: Logger): EventSubscriptions;
-
-/**
- * EventBus - Event Pub/Sub Layer
- *
- * Single Responsibility: Event pub/sub only
- * - Publishes events to subscribers
- * - Manages subscriptions (resource-scoped and global)
- *
- * Does NOT handle:
- * - Event persistence (see EventLog)
- * - View updates (see ViewManager)
- */
-
-/**
- * EventBus wraps EventSubscriptions with a clean API
- * Uses bare ResourceId for subscriptions
- */
-declare class EventBus {
-    readonly subscriptions: EventSubscriptions;
-    private logger?;
-    constructor(logger?: Logger);
-    /**
-     * 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)
-     */
-    publish(event: StoredEvent): Promise<void>;
-    /**
-     * 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: ResourceId, callback: EventCallback): EventSubscription;
-    /**
-     * Subscribe to all system-level events
-     * @param callback - Event callback function
-     * @returns EventSubscription with unsubscribe function
-     */
-    subscribeGlobal(callback: EventCallback): EventSubscription;
-    /**
-     * Unsubscribe from resource events
-     * @param resourceId - Branded ResourceId (from @semiont/core)
-     * @param callback - Event callback function to remove
-     */
-    unsubscribe(resourceId: ResourceId, callback: EventCallback): void;
-    /**
-     * Unsubscribe from global events
-     * @param callback - Event callback function to remove
-     */
-    unsubscribeGlobal(callback: EventCallback): void;
-    /**
-     * Get subscriber count for a resource
-     * @param resourceId - Branded ResourceId (from @semiont/core)
-     * @returns Number of active subscribers
-     */
-    getSubscriberCount(resourceId: ResourceId): number;
-    /**
-     * Get total number of active subscriptions across all resources
-     */
-    getTotalSubscriptions(): number;
-    /**
-     * Get total number of global subscriptions
-     */
-    getGlobalSubscriptionCount(): number;
-}
-
 /**
  * View Materializer - Materialized View Management
  *
@@ -334,6 +208,15 @@ declare class EventBus {
  * @see docs/EVENT-STORE.md#viewmaterializer for architecture details
  */
 
+/**
+ * Minimal structural type for the event log dependency of `rebuildAll`.
+ * Avoids importing the concrete EventLog class from a sibling directory and
+ * keeps the materializer independent of the event-log implementation.
+ */
+interface RebuildEventSource {
+    getEvents(resourceId: ResourceId): Promise<StoredEvent[]>;
+    getAllResourceIds(): Promise<ResourceId[]>;
+}
 interface ViewMaterializerConfig {
     basePath: string;
 }
@@ -354,11 +237,11 @@ declare class ViewMaterializer {
      * Materialize view incrementally with a single event
      * Falls back to full rebuild if view doesn't exist
      */
-    materializeIncremental(resourceId: ResourceId, event: ResourceEvent, getAllEvents: () => Promise<StoredEvent[]>): Promise<void>;
+    materializeIncremental(resourceId: ResourceId, event: PersistedEvent, getAllEvents: () => Promise<StoredEvent[]>): Promise<void>;
     /**
      * 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.
      */
     private materializeStorageUriIndex;
@@ -374,6 +257,16 @@ declare class ViewMaterializer {
      * Apply an event to ResourceAnnotations (annotation collections only)
      */
     private applyEventToAnnotations;
+    /**
+     * 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.
+     */
+    rebuildAll(eventLog: RebuildEventSource): Promise<void>;
     /**
      * Materialize entity types view - System-level view
      */
@@ -410,13 +303,20 @@ declare class ViewManager {
      * @param event - Resource event (from @semiont/core)
      * @param getAllEvents - Function to retrieve all events for rebuild if needed
      */
-    materializeResource(resourceId: ResourceId, event: ResourceEvent, getAllEvents: () => Promise<StoredEvent[]>): Promise<void>;
+    materializeResource(resourceId: ResourceId, event: PersistedEvent, getAllEvents: () => Promise<StoredEvent[]>): Promise<void>;
     /**
      * Update system-level view (currently only entity types)
      * @param eventType - Type of system event
      * @param payload - Event payload
      */
     materializeSystem(eventType: string, payload: any): Promise<void>;
+    /**
+     * 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.
+     */
+    rebuildAll(eventLog: RebuildEventSource): Promise<void>;
     /**
      * Get resource view (builds from events if needed)
      * @param resourceId - Branded ResourceId (from @semiont/core)
@@ -429,14 +329,15 @@ declare class ViewManager {
 /**
  * EventStore - Orchestration Layer
  *
- * Coordinates event sourcing operations across 3 focused components:
+ * Coordinates event sourcing operations:
  * - EventLog: Event persistence (append, retrieve, query)
- * - EventBus: Pub/sub notifications (publish, subscribe)
- * - ViewManager: View updates (resource and system)
+ * - ViewManager: View materialization (resource and system)
+ * - Core EventBus: Publishes StoredEvent to typed channels after persistence
  *
- * Thin coordination layer - delegates all work to specialized components.
- *
- * @see docs/EVENT-STORE.md for complete architecture documentation
+ * appendEvent() is the single write path:
+ *   1. Persist to EventLog
+ *   2. Materialize views
+ *   3. Publish StoredEvent to global and resource-scoped typed channels
  */
 
 /**
@@ -446,16 +347,22 @@ declare class ViewManager {
  */
 declare class EventStore {
     readonly log: EventLog;
-    readonly bus: EventBus;
     readonly views: ViewManager;
     readonly viewStorage: ViewStorage;
-    readonly coreEventBus?: EventBus$1;
-    constructor(project: SemiontProject, stateDir: string, viewStorage: ViewStorage, coreEventBus?: EventBus$1, logger?: Logger);
+    readonly coreEventBus: EventBus;
+    constructor(project: SemiontProject, stateDir: string, viewStorage: ViewStorage, coreEventBus: EventBus, logger?: Logger);
     /**
      * Append an event to the store
      * Coordinates: persistence → view → notification
-     */
-    appendEvent(event: Omit<ResourceEvent, 'id' | 'timestamp'>): Promise<StoredEvent>;
+     *
+     * @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.
+     */
+    appendEvent(event: EventInput, options?: {
+        correlationId?: string;
+    }): Promise<StoredEvent>;
 }
 
 /**
@@ -469,11 +376,11 @@ declare class EventStore {
  * Create and initialize an EventStore instance
  *
  * @param project - SemiontProject instance
- * @param eventBus - Optional @semiont/core EventBus for publishing domain events
+ * @param eventBus - @semiont/core EventBus for publishing domain events
  * @param logger - Optional logger for structured logging
  * @returns Configured EventStore instance ready for use
  */
-declare function createEventStore(project: SemiontProject, eventBus?: EventBus$1, logger?: Logger): EventStore;
+declare function createEventStore(project: SemiontProject, eventBus: EventBus, logger?: Logger): EventStore;
 
 /**
  * Sharding Utilities
@@ -638,8 +545,6 @@ declare class EventQuery {
  * - prevEventHash links to previous event's checksum
  * - Each event's checksum is verified against its payload
  * - Detects broken chains and tampered events
- *
- * @see docs/EVENT-STORE.md#eventvalidator for architecture details
  */
 
 interface ValidationResult {
@@ -678,4 +583,4 @@ declare class EventValidator {
  */
 declare function generateAnnotationId(): string;
 
-export { EventBus, type EventCallback, EventLog, type EventLogConfig, EventQuery, EventStorage, type EventStorageConfig, EventStore, type EventSubscription, EventSubscriptions, EventValidator, FilesystemViewStorage, ResourceNotFoundError, type ResourceView, type StorageUriEntry, ViewManager, type ViewManagerConfig, ViewMaterializer, type ViewStorage, createEventStore, generateAnnotationId, getEventSubscriptions, getShardPath, jumpConsistentHash, removeStorageUriEntry, resolveStorageUri, sha256, writeStorageUriEntry };
+export { EventLog, type EventLogConfig, EventQuery, EventStorage, type EventStorageConfig, EventStore, EventValidator, FilesystemViewStorage, ResourceNotFoundError, type ResourceView, type StorageUriEntry, ViewManager, type ViewManagerConfig, ViewMaterializer, type ViewStorage, createEventStore, generateAnnotationId, getShardPath, jumpConsistentHash, removeStorageUriEntry, resolveStorageUri, sha256, writeStorageUriEntry };