@semiont/event-sourcing 0.5.2 → 0.5.4

package/dist/index.d.ts

@@ -1,571 +1,25 @@
-import { ResourceId, ResourceDescriptor, ResourceAnnotations, Logger, EventInput, StoredEvent, EventQuery as EventQuery$1, PersistedEvent, EventBus } from '@semiont/core';
-import { SemiontProject } from '@semiont/core/node';
-
 /**
- * View Storage - Materialized Views
+ * @semiont/event-sourcing
  *
- * Stores materialized views of resource state and annotations
- * Built from event streams, can be rebuilt at any time
+ * Event sourcing infrastructure for Semiont
  *
- * Stores both ResourceDescriptor metadata and ResourceAnnotations, but keeps them logically separate
- */
-
-interface ResourceView {
-    resource: ResourceDescriptor;
-    annotations: ResourceAnnotations;
-}
-interface ViewStorage {
-    save(resourceId: ResourceId, view: ResourceView): Promise<void>;
-    get(resourceId: ResourceId): Promise<ResourceView | null>;
-    delete(resourceId: ResourceId): Promise<void>;
-    exists(resourceId: ResourceId): Promise<boolean>;
-    getAll(): Promise<ResourceView[]>;
-}
-declare class FilesystemViewStorage implements ViewStorage {
-    private basePath;
-    private logger?;
-    constructor(project: SemiontProject, logger?: Logger);
-    private getProjectionPath;
-    save(resourceId: ResourceId, projection: ResourceView): Promise<void>;
-    get(resourceId: ResourceId): Promise<ResourceView | null>;
-    delete(resourceId: ResourceId): Promise<void>;
-    exists(resourceId: ResourceId): Promise<boolean>;
-    getAll(): Promise<ResourceView[]>;
-}
-
-/**
- * Event Storage - Physical Storage Layer
- *
- * Handles file I/O operations for event storage:
- * - JSONL file writing/reading
- * - 4-hex sharding (65,536 shards)
- * - File rotation
- * - Event stream initialization
- *
- * @see docs/EVENT-STORE.md#eventstorage for architecture details
- */
-
-interface EventStorageConfig {
-    maxEventsPerFile?: number;
-    enableSharding?: boolean;
-    numShards?: number;
-    enableCompression?: boolean;
-}
-/**
- * EventStorage handles physical storage of events
- * Owns: file I/O, sharding, AND sequence/hash tracking
- */
-declare class EventStorage {
-    private config;
-    private project;
-    private logger?;
-    private resourceSequences;
-    private currentFiles;
-    constructor(project: SemiontProject, config?: EventStorageConfig, logger?: Logger);
-    /**
-     * Calculate shard path for a resource ID
-     * Uses jump consistent hash for uniform distribution
-     * Special case: __system__ events bypass sharding
-     */
-    getShardPath(resourceId: ResourceId): string;
-    /**
-     * Get full path to resource's event directory
-     */
-    getResourcePath(resourceId: ResourceId): string;
-    /**
-     * Initialize directory structure for a resource's event stream
-     * Also loads sequence number and last hash if stream exists
-     */
-    initializeResourceStream(resourceId: ResourceId): Promise<void>;
-    /**
-     * Append an event - handles EVERYTHING for event creation
-     * Creates ID, timestamp, metadata, sequence tracking, and writes to disk.
-     *
-     * Integrity is provided by git at the commit level (when gitSync is enabled),
-     * not by per-event chaining metadata. Per-event signatures (the unused
-     * `EventSignature` field on StoredEvent) are the planned mechanism for
-     * cross-KB authorship binding when federation becomes a real requirement.
-     *
-     * @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: EventInput, resourceId: ResourceId, options?: {
-        correlationId?: string;
-    }): Promise<StoredEvent>;
-    /**
-     * Write an event to storage (append to JSONL)
-     * Internal method - use appendEvent() instead
-     *
-     * Uses currentFiles cache to avoid fs.readdir() + countEventsInFile() on every append.
-     * Cache is populated on first append (cold start) and updated on rotation.
-     */
-    private writeEvent;
-    /**
-     * Count events in a specific file
-     */
-    countEventsInFile(resourceId: ResourceId, filename: string): Promise<number>;
-    /**
-     * Read all events from a specific file
-     */
-    readEventsFromFile(resourceId: ResourceId, filename: string): Promise<StoredEvent[]>;
-    /**
-     * Get list of event files for a resource (sorted by sequence)
-     */
-    getEventFiles(resourceId: ResourceId): Promise<string[]>;
-    /**
-     * Create a new event file for rotation
-     */
-    createNewEventFile(resourceId: ResourceId): Promise<string>;
-    /**
-     * Get the last event from a specific file
-     */
-    getLastEvent(resourceId: ResourceId, filename: string): Promise<StoredEvent | null>;
-    /**
-     * Get all events for a resource across all files
-     */
-    getAllEvents(resourceId: ResourceId): Promise<StoredEvent[]>;
-    /**
-     * Get all resource IDs by scanning shard directories
-     */
-    getAllResourceIds(): Promise<ResourceId[]>;
-    /**
-     * Create filename for event file
-     */
-    private createEventFilename;
-    /**
-     * Get current sequence number for a resource
-     */
-    getSequenceNumber(resourceId: ResourceId): number;
-    /**
-     * Increment and return next sequence number for a resource
-     */
-    getNextSequenceNumber(resourceId: ResourceId): number;
-}
-
-/**
- * EventLog - Event Persistence Layer
- *
- * Single Responsibility: Event persistence only
- * - Appends events to storage (JSONL files)
- * - Retrieves events by resource
- * - Queries events with filters
- *
- * Does NOT handle:
- * - Pub/sub notifications (see EventBus)
- * - View updates (see ViewManager)
- */
-
-interface EventLogConfig {
-    project: SemiontProject;
-    enableSharding?: boolean;
-    maxEventsPerFile?: number;
-}
-declare class EventLog {
-    readonly storage: EventStorage;
-    constructor(config: EventLogConfig, logger?: Logger);
-    /**
-     * 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: EventInput, resourceId: ResourceId, options?: {
-        correlationId?: string;
-    }): Promise<StoredEvent>;
-    /**
-     * Get all events for a resource
-     * @param resourceId - Branded ResourceId (from @semiont/core)
-     */
-    getEvents(resourceId: ResourceId): Promise<StoredEvent[]>;
-    /**
-     * Get all resource IDs
-     * @returns Array of branded ResourceId types
-     */
-    getAllResourceIds(): Promise<ResourceId[]>;
-    /**
-     * Query events with filter
-     * @param resourceId - Branded ResourceId (from @semiont/core)
-     * @param filter - Optional event filter
-     */
-    queryEvents(resourceId: ResourceId, filter?: EventQuery$1): Promise<StoredEvent[]>;
-}
-
-/**
- * View Materializer - Materialized View Management
- *
- * Materializes resource views from events:
- * - Full view materialization from scratch
- * - Incremental view updates
- * - System-level views (entity types)
- *
- * @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;
-}
-/**
- * ViewMaterializer builds and maintains materialized views from events
- */
-declare class ViewMaterializer {
-    private viewStorage;
-    private config;
-    private logger?;
-    constructor(viewStorage: ViewStorage, config: ViewMaterializerConfig, logger?: Logger);
-    /**
-     * Materialize resource view from events
-     * Loads existing view if cached, otherwise rebuilds from events
-     */
-    materialize(events: StoredEvent[], resourceId: ResourceId): Promise<ResourceView | null>;
-    /**
-     * Materialize view incrementally with a single event
-     * Falls back to full rebuild if view doesn't exist
-     */
-    materializeIncremental(resourceId: ResourceId, event: PersistedEvent, getAllEvents: () => Promise<StoredEvent[]>): Promise<void>;
-    /**
-     * Update the storage-uri index in response to an event.
-     *
-     * Only yield:created (with storageUri), yield:moved, need index changes.
-     * resource.archived / resource.unarchived do NOT modify the index.
-     */
-    private materializeStorageUriIndex;
-    /**
-     * Materialize view from event list (full rebuild)
-     */
-    private materializeFromEvents;
-    /**
-     * Apply an event to ResourceDescriptor state (metadata only)
-     */
-    private applyEventToResource;
-    /**
-     * 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
-     */
-    materializeEntityTypes(entityType: string): Promise<void>;
-}
-
-/**
- * ViewManager - Materialized View Management Layer
- *
- * Single Responsibility: View updates only
- * - Updates resource views from events
- * - Updates system views (entity types)
- * - Rebuilds views when needed
- *
- * Does NOT handle:
- * - Event persistence (see EventLog)
- * - Pub/sub notifications (see EventBus)
- */
-
-interface ViewManagerConfig {
-    basePath: string;
-}
-/**
- * ViewManager wraps ViewMaterializer with a clean API
- * Handles both resource and system-level views
- *
- * ## Per-resource serialization
- *
- * `materializeResource` runs read-modify-write cycles on the view file for
- * a given resource (load JSON → apply event → save JSON). When multiple
- * events arrive for the same resource in rapid succession — the canonical
- * example is the reference-detection worker emitting `mark:added` +
- * `job:progress` + `job:completed` within a few milliseconds — concurrent
- * RMW cycles will clobber each other, losing events and occasionally
- * corrupting the view file entirely.
- *
- * ViewManager serializes these via `serializePerKey` from `@semiont/core`:
- * each incoming `materializeResource` call chains onto the previous one
- * for the same `resourceId`, so the work runs strictly sequentially per
- * resource while still parallelizing across different resources. System
- * events go through their own shared chain (keyed by a sentinel).
- *
- * Why this shape and not RxJS `groupBy + concatMap`:
- * ViewManager is called **synchronously** by `EventStore.appendEvent` — it
- * must block the caller until the view is written, so SSE subscribers
- * that see the subsequently-published event get the up-to-date view (a
- * read-your-writes guarantee). The RxJS stream-consumer pattern used by
- * `Smelter`, `GraphDBConsumer`, and `Gatherer` can't provide that
- * guarantee because it's fire-and-forget from the publisher's perspective.
- * Both patterns solve "serialize work per resource" — see also
- * `packages/core/src/serialize-per-key.ts` for the shared primitive.
- */
-declare class ViewManager {
-    readonly materializer: ViewMaterializer;
-    private resourceChains;
-    private systemChains;
-    private static readonly SYSTEM_KEY;
-    constructor(viewStorage: ViewStorage, config: ViewManagerConfig, logger?: Logger);
-    /**
-     * Update resource view with a new event.
-     * Serialized per resource — see class doc.
-     *
-     * @param resourceId - Branded ResourceId (from @semiont/core)
-     * @param event - Resource event (from @semiont/core)
-     * @param getAllEvents - Function to retrieve all events for rebuild if needed
-     */
-    materializeResource(resourceId: ResourceId, event: PersistedEvent, getAllEvents: () => Promise<StoredEvent[]>): Promise<void>;
-    /**
-     * Update system-level view (currently only entity types).
-     * Serialized through a shared chain — see class doc.
-     */
-    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)
-     * @param events - Stored events for the resource (from @semiont/core)
-     * @returns Resource view or null if no events
-     */
-    getOrMaterialize(resourceId: ResourceId, events: StoredEvent[]): Promise<ResourceView | null>;
-}
-
-/**
- * EventStore - Orchestration Layer
- *
- * Coordinates event sourcing operations:
+ * Provides:
+ * - EventStore: Orchestration layer for event sourcing
  * - EventLog: Event persistence (append, retrieve, query)
  * - ViewManager: View materialization (resource and system)
- * - Core EventBus: Publishes StoredEvent to typed channels after persistence
- *
- * appendEvent() is the single write path:
- *   1. Persist to EventLog
- *   2. Materialize views
- *   3. Enrich (optional callback — attach post-materialization data)
- *   4. Publish StoredEvent to global and resource-scoped typed channels
- */
-
-type EnrichEvent = (event: StoredEvent, resourceId: ResourceId) => Promise<StoredEvent>;
-declare class EventStore {
-    readonly log: EventLog;
-    readonly views: ViewManager;
-    readonly viewStorage: ViewStorage;
-    readonly coreEventBus: EventBus;
-    private enrichEvent;
-    constructor(project: SemiontProject, stateDir: string, viewStorage: ViewStorage, coreEventBus: EventBus, logger?: Logger);
-    setEnrichEvent(fn: EnrichEvent): void;
-    /**
-     * Append an event to the store
-     * Coordinates: persistence → view → enrich → notification
-     *
-     * @param options.correlationId - Optional id propagated from a command.
-     */
-    appendEvent(event: EventInput, options?: {
-        correlationId?: string;
-    }): Promise<StoredEvent>;
-}
-
-/**
- * Event Store Factory
- *
- * Factory function for creating EventStore instances with standard configuration.
- * This is the canonical way to instantiate an EventStore.
- */
-
-/**
- * Create and initialize an EventStore instance
- *
- * @param project - SemiontProject instance
- * @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, logger?: Logger): EventStore;
-
-/**
- * Sharding Utilities
- *
- * Shared utilities for consistent sharding across all storage layers
- * Uses Google's Jump Consistent Hash algorithm for even distribution
- */
-/**
- * TEMPORARY: Simple modulo-based hash sharding
- *
- * ⚠️ TODO: Replace with proper Jump Consistent Hash implementation
- *
- * This is a TEMPORARY implementation using simple modulo. It works and provides
- * good distribution, but does NOT provide the minimal reshuffling property of
- * Jump Consistent Hash when changing bucket counts.
- *
- * The proper implementation should use Google's Jump Consistent Hash algorithm:
- * Reference: "A Fast, Minimal Memory, Consistent Hash Algorithm" by Lamping & Veach (2014)
- * https://arxiv.org/abs/1406.2294
- *
- * Working implementations exist in npm packages like:
- * - jumphash (https://www.npmjs.com/package/jumphash)
- * - jump-gouache (https://github.com/bhoudu/jump-gouache)
- *
- * The algorithm requires proper 64-bit integer handling with BigInt to avoid
- * precision loss in JavaScript. The previous attempt failed due to incorrect
- * BigInt arithmetic in the while loop condition.
- *
- * Until replaced, this modulo approach will cause ALL data to be reshuffled
- * if bucket count changes, rather than the optimal O(n/k) reshuffling that
- * Jump Consistent Hash provides.
- *
- * @param key - The key to hash (typically a resource ID)
- * @param numBuckets - Number of shards/buckets (default: 65536 for 4-hex sharding)
- * @returns Shard number (0 to numBuckets-1)
- */
-declare function jumpConsistentHash(key: string, numBuckets?: number): number;
-/**
- * Get 4-hex shard path for a key
- *
- * @param key - The key to hash (typically a resource ID)
- * @param numBuckets - Number of shards (default: 65536)
- * @returns Path segments like ['ab', 'cd']
- */
-declare function getShardPath(key: string, numBuckets?: number): [string, string];
-/**
- * Calculate SHA-256 hash of data
- */
-declare function sha256(data: string | object): string;
-
-/**
- * Storage URI Index
- *
- * Projection that maps file:// URIs → resourceIds.
- * Sharded at:
- *   {projectionsDir}/storage-uri/{ab}/{cd}/{uri-hash}.json
- *
- * where {ab}/{cd} comes from jumpConsistentHash(uri) and
- * {uri-hash} is the SHA-256 of the URI string.
- *
- * Each file contains: { uri: string; resourceId: string }
- *
- * This index is maintained by ViewMaterializer (the single owner).
- * It is never modified by Stower or other actors.
- *
- * Archive/unarchive do NOT remove entries from this index.
- * Archived resources are marked in the ResourceView (archived: true)
- * but remain findable by URI.
- */
-interface StorageUriEntry {
-    uri: string;
-    resourceId: string;
-}
-/**
- * Thrown when a URI is not found in the storage-uri index.
- */
-declare class ResourceNotFoundError extends Error {
-    readonly uri: string;
-    constructor(uri: string);
-}
-/**
- * Resolve a file:// URI to a resourceId using the storage-uri index.
- *
- * @param projectionsDir - Path to the projections directory
- * @param uri - file:// URI (e.g. "file://docs/overview.md")
- * @returns resourceId
- * @throws ResourceNotFoundError if URI is not in the index
- */
-declare function resolveStorageUri(projectionsDir: string, uri: string): Promise<string>;
-/**
- * Write a URI → resourceId mapping to the index.
- *
- * Called by ViewMaterializer when handling resource.created, resource.moved.
- *
- * @param projectionsDir - Path to the projections directory
- * @param uri - file:// URI
- * @param resourceId - resourceId to map to
- */
-declare function writeStorageUriEntry(projectionsDir: string, uri: string, resourceId: string): Promise<void>;
-/**
- * Remove a URI entry from the index.
- *
- * Called by ViewMaterializer when handling resource.moved (old URI only).
- * NOT called on resource.archived — archived resources retain their index entry.
- *
- * @param projectionsDir - Path to the projections directory
- * @param uri - file:// URI to remove
- */
-declare function removeStorageUriEntry(projectionsDir: string, uri: string): Promise<void>;
-
-/**
- * Event Query - Read Operations
- *
- * Handles querying and reading events from storage:
- * - Query events with filters (type, user, timestamp, sequence)
- * - Get all events for a resource
- * - Get last event from a file
- * - Efficient streaming reads from JSONL files
- *
- * @see docs/EVENT-STORE.md#eventquery for architecture details
- */
-
-/**
- * EventQuery handles all read operations for events
- * Uses EventStorage for file access, adds query filtering
- */
-declare class EventQuery {
-    private eventStorage;
-    constructor(eventStorage: EventStorage);
-    /**
-     * Query events with filters
-     * Supports filtering by: userId, eventTypes, timestamps, sequence number, limit
-     */
-    queryEvents(query: EventQuery$1): Promise<StoredEvent[]>;
-    /**
-     * Get all events for a specific resource (no filters)
-     */
-    getResourceEvents(resourceId: ResourceId): Promise<StoredEvent[]>;
-    /**
-     * Get the last event from a specific file
-     * Useful for initializing sequence numbers and last hashes
-     */
-    getLastEvent(resourceId: ResourceId, filename: string): Promise<StoredEvent | null>;
-    /**
-     * Get the latest event for a resource across all files
-     */
-    getLatestEvent(resourceId: ResourceId): Promise<StoredEvent | null>;
-    /**
-     * Get event count for a resource
-     */
-    getEventCount(resourceId: ResourceId): Promise<number>;
-    /**
-     * Check if a resource has any events
-     */
-    hasEvents(resourceId: ResourceId): Promise<boolean>;
-}
-
-/**
- * Identifier utilities for event sourcing
- */
-/**
- * Generate a unique annotation ID (bare nanoid)
- *
- * @returns A bare annotation ID (e.g., "V1StGXR8_Z5jdHi6B-myT")
- */
-declare function generateAnnotationId(): string;
-
-export { type EnrichEvent, EventLog, type EventLogConfig, EventQuery, EventStorage, type EventStorageConfig, EventStore, FilesystemViewStorage, ResourceNotFoundError, type ResourceView, type StorageUriEntry, ViewManager, type ViewManagerConfig, ViewMaterializer, type ViewStorage, createEventStore, generateAnnotationId, getShardPath, jumpConsistentHash, removeStorageUriEntry, resolveStorageUri, sha256, writeStorageUriEntry };
+ * - ViewStorage: Interface and filesystem implementation for materialized views
+ */
+export { EventStore, type EnrichEvent } from './event-store';
+export { createEventStore } from './event-store-factory';
+export { EventLog, type EventLogConfig } from './event-log';
+export { ViewManager, type ViewManagerConfig } from './view-manager';
+export { type EventStorageConfig } from './storage/event-storage';
+export { EventStorage } from './storage/event-storage';
+export { type ViewStorage, type ResourceView, FilesystemViewStorage, } from './storage/view-storage';
+export { getShardPath, sha256, jumpConsistentHash } from './storage/shard-utils';
+export { resolveStorageUri, writeStorageUriEntry, removeStorageUriEntry, ResourceNotFoundError, type StorageUriEntry, } from './storage/storage-uri-index';
+export { EventQuery } from './query/event-query';
+export { ViewMaterializer } from './views/view-materializer';
+export { applyEntityTypeAdded, applyTagSchemaAdded, type ApplyTagSchemaAddedResult, } from './views/projection-reducers';
+export { generateAnnotationId } from './identifier-utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGrE,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,6BAA6B,CAAC;AAIrC,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,yBAAyB,GAC/B,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC"}