@semiont/event-sourcing 0.5.4 → 0.5.5

package/dist/event-log.d.ts

@@ -1,51 +0,0 @@
-/**
- * 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)
- */
-import { type ResourceId, type StoredEvent, type EventQuery, type EventInput, type Logger } from '@semiont/core';
-import type { SemiontProject } from '@semiont/core/node';
-import { EventStorage } from './storage/event-storage';
-export interface EventLogConfig {
-    project: SemiontProject;
-    enableSharding?: boolean;
-    maxEventsPerFile?: number;
-}
-export 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): Promise<StoredEvent[]>;
-}
-//# sourceMappingURL=event-log.d.ts.map

package/dist/event-log.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"event-log.d.ts","sourceRoot":"","sources":["../src/event-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,MAAM,EAAE,MAAM,eAAe,CAAC;AACjH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,cAAc,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,QAAQ;IAEnB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;gBAEnB,MAAM,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,MAAM;IAOnD;;;;;;OAMG;IACG,MAAM,CACV,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,UAAU,EACtB,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACnC,OAAO,CAAC,WAAW,CAAC;IAIvB;;;OAGG;IACG,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAI/D;;;OAGG;IACG,iBAAiB,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAIhD;;;;OAIG;IACG,WAAW,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;CAavF"}

package/dist/event-store-factory.d.ts

@@ -1,19 +0,0 @@
-/**
- * Event Store Factory
- *
- * Factory function for creating EventStore instances with standard configuration.
- * This is the canonical way to instantiate an EventStore.
- */
-import type { SemiontProject } from '@semiont/core/node';
-import type { EventBus as CoreEventBus, Logger } from '@semiont/core';
-import { EventStore } from './event-store';
-/**
- * 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
- */
-export declare function createEventStore(project: SemiontProject, eventBus: CoreEventBus, logger?: Logger): EventStore;
-//# sourceMappingURL=event-store-factory.d.ts.map

package/dist/event-store-factory.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"event-store-factory.d.ts","sourceRoot":"","sources":["../src/event-store-factory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAG3C;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,YAAY,EACtB,MAAM,CAAC,EAAE,MAAM,GACd,UAAU,CAUZ"}

package/dist/event-store.d.ts

@@ -1,40 +0,0 @@
-/**
- * EventStore - Orchestration Layer
- *
- * Coordinates event sourcing operations:
- * - 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
- */
-import type { EventInput, StoredEvent, ResourceId, Logger } from '@semiont/core';
-import { EventBus as CoreEventBus } from '@semiont/core';
-import type { SemiontProject } from '@semiont/core/node';
-import type { ViewStorage } from './storage/view-storage';
-import { EventLog } from './event-log';
-import { ViewManager } from './view-manager';
-export type EnrichEvent = (event: StoredEvent, resourceId: ResourceId) => Promise<StoredEvent>;
-export declare class EventStore {
-    readonly log: EventLog;
-    readonly views: ViewManager;
-    readonly viewStorage: ViewStorage;
-    readonly coreEventBus: CoreEventBus;
-    private enrichEvent;
-    constructor(project: SemiontProject, stateDir: string, viewStorage: ViewStorage, coreEventBus: CoreEventBus, 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>;
-}
-//# sourceMappingURL=event-store.d.ts.map

package/dist/event-store.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"event-store.d.ts","sourceRoot":"","sources":["../src/event-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,UAAU,EACV,MAAM,EACP,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,WAAW,EAA0B,MAAM,gBAAgB,CAAC;AAErE,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;AAE/F,qBAAa,UAAU;IACrB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,OAAO,CAAC,WAAW,CAA4B;gBAG7C,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,WAAW,EACxB,YAAY,EAAE,YAAY,EAC1B,MAAM,CAAC,EAAE,MAAM;IAajB,cAAc,CAAC,EAAE,EAAE,WAAW,GAAG,IAAI;IAIrC;;;;;OAKG;IACG,WAAW,CACf,KAAK,EAAE,UAAU,EACjB,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACnC,OAAO,CAAC,WAAW,CAAC;CAoCxB"}

package/dist/identifier-utils.d.ts

@@ -1,10 +0,0 @@
-/**
- * Identifier utilities for event sourcing
- */
-/**
- * Generate a unique annotation ID (bare nanoid)
- *
- * @returns A bare annotation ID (e.g., "V1StGXR8_Z5jdHi6B-myT")
- */
-export declare function generateAnnotationId(): string;
-//# sourceMappingURL=identifier-utils.d.ts.map

package/dist/identifier-utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"identifier-utils.d.ts","sourceRoot":"","sources":["../src/identifier-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"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"}

package/dist/query/event-query.d.ts

@@ -1,48 +0,0 @@
-/**
- * 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
- */
-import type { StoredEvent, EventQuery as EventQueryType, ResourceId } from '@semiont/core';
-import type { EventStorage } from '../storage/event-storage';
-/**
- * EventQuery handles all read operations for events
- * Uses EventStorage for file access, adds query filtering
- */
-export declare class EventQuery {
-    private eventStorage;
-    constructor(eventStorage: EventStorage);
-    /**
-     * Query events with filters
-     * Supports filtering by: userId, eventTypes, timestamps, sequence number, limit
-     */
-    queryEvents(query: EventQueryType): 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>;
-}
-//# sourceMappingURL=event-query.d.ts.map

package/dist/query/event-query.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"event-query.d.ts","sourceRoot":"","sources":["../../src/query/event-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,IAAI,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D;;;GAGG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,YAAY;gBAAZ,YAAY,EAAE,YAAY;IAE9C;;;OAGG;IACG,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAuChE;;OAEG;IACG,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAIvE;;;OAGG;IACG,YAAY,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAIzF;;OAEG;IACG,cAAc,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAezE;;OAEG;IACG,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAK5D;;OAEG;IACG,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;CAI1D"}

package/dist/storage/event-storage.d.ts

@@ -1,111 +0,0 @@
-/**
- * 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
- */
-import type { StoredEvent, EventInput, ResourceId, Logger } from '@semiont/core';
-import type { SemiontProject } from '@semiont/core/node';
-export 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
- */
-export 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;
-}
-//# sourceMappingURL=event-storage.d.ts.map

package/dist/storage/event-storage.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"event-storage.d.ts","sourceRoot":"","sources":["../../src/storage/event-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAE,WAAW,EAAiC,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAEhH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAGzD,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAA+B;IAC7C,OAAO,CAAC,OAAO,CAAiB;IAChC,OAAO,CAAC,MAAM,CAAC,CAAS;IAGxB,OAAO,CAAC,iBAAiB,CAAkC;IAE3D,OAAO,CAAC,YAAY,CAAgE;gBAExE,OAAO,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,kBAAkB,EAAE,MAAM,CAAC,EAAE,MAAM;IAWjF;;;;OAIG;IACH,YAAY,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM;IAgB5C;;OAEG;IACH,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM;IAK/C;;;OAGG;IACG,wBAAwB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA+CrE;;;;;;;;;;;;OAYG;IACG,WAAW,CACf,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,UAAU,EACtB,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GACnC,OAAO,CAAC,WAAW,CAAC;IA+BvB;;;;;;OAMG;YACW,UAAU;IAoCxB;;OAEG;IACG,iBAAiB,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBlF;;OAEG;IACG,kBAAkB,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAyC1F;;OAEG;IACG,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAwB9D;;OAEG;IACG,kBAAkB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBjE;;OAEG;IACG,YAAY,CAAC,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAMzF;;OAEG;IACG,YAAY,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAYlE;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAkChD;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAQ3B;;OAEG;IACH,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM;IAIjD;;OAEG;IACH,qBAAqB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM;CAOtD"}

package/dist/storage/shard-utils.d.ts

@@ -1,56 +0,0 @@
-/**
- * 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)
- */
-export declare function jumpConsistentHash(key: string, numBuckets?: number): number;
-/**
- * Convert shard number to 4-hex directory path (ab/cd)
- *
- * @param shardId - Shard number (0-65535)
- * @returns Path segments like ['ab', 'cd']
- */
-export declare function shardIdToPath(shardId: number): [string, string];
-/**
- * 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']
- */
-export declare function getShardPath(key: string, numBuckets?: number): [string, string];
-/**
- * Calculate SHA-256 hash of data
- */
-export declare function sha256(data: string | object): string;
-//# sourceMappingURL=shard-utils.d.ts.map

package/dist/storage/shard-utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"shard-utils.d.ts","sourceRoot":"","sources":["../../src/storage/shard-utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,GAAE,MAAc,GAAG,MAAM,CAGlF;AAcD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAU/D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,GAAE,MAAc,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAGtF;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAGpD"}

package/dist/storage/storage-uri-index.d.ts

@@ -1,60 +0,0 @@
-/**
- * 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.
- */
-export interface StorageUriEntry {
-    uri: string;
-    resourceId: string;
-}
-/**
- * Thrown when a URI is not found in the storage-uri index.
- */
-export 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
- */
-export 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
- */
-export 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
- */
-export declare function removeStorageUriEntry(projectionsDir: string, uri: string): Promise<void>;
-//# sourceMappingURL=storage-uri-index.d.ts.map

package/dist/storage/storage-uri-index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"storage-uri-index.d.ts","sourceRoot":"","sources":["../../src/storage/storage-uri-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM;gBAAX,GAAG,EAAE,MAAM;CAIjC;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,cAAc,EAAE,MAAM,EACtB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,cAAc,EAAE,MAAM,EACtB,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,cAAc,EAAE,MAAM,EACtB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/storage/view-storage.d.ts

@@ -1,33 +0,0 @@
-/**
- * View Storage - Materialized Views
- *
- * Stores materialized views of resource state and annotations
- * Built from event streams, can be rebuilt at any time
- *
- * Stores both ResourceDescriptor metadata and ResourceAnnotations, but keeps them logically separate
- */
-import type { SemiontProject } from '@semiont/core/node';
-import type { ResourceAnnotations, ResourceDescriptor, ResourceId, Logger } from '@semiont/core';
-export interface ResourceView {
-    resource: ResourceDescriptor;
-    annotations: ResourceAnnotations;
-}
-export 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[]>;
-}
-export 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[]>;
-}
-//# sourceMappingURL=view-storage.d.ts.map

package/dist/storage/view-storage.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"view-storage.d.ts","sourceRoot":"","sources":["../../src/storage/view-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAGjG,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,WAAW,EAAE,mBAAmB,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,GAAG,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC1D,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,MAAM,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CACnC;AAED,qBAAa,qBAAsB,YAAW,WAAW;IACvD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAC,CAAS;gBAEZ,OAAO,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,MAAM;IAKpD,OAAO,CAAC,iBAAiB;IAMnB,IAAI,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBrE,GAAG,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IA8BzD,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAa7C,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAWhD,MAAM,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;CAsCxC"}

package/dist/view-manager.d.ts

@@ -1,84 +0,0 @@
-/**
- * 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)
- */
-import { type ResourceId, type PersistedEvent, type StoredEvent, type Logger } from '@semiont/core';
-import { ViewMaterializer, type RebuildEventSource } from './views/view-materializer';
-import type { ViewStorage, ResourceView } from './storage/view-storage';
-export 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.
- */
-export 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 (entity types + tag schemas today).
-     * 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>;
-}
-//# sourceMappingURL=view-manager.d.ts.map

package/dist/view-manager.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"view-manager.d.ts","sourceRoot":"","sources":["../src/view-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,WAAW,EAAE,KAAK,MAAM,EAAmB,MAAM,eAAe,CAAC;AACrH,OAAO,EAAE,gBAAgB,EAA+B,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACnH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAExE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,WAAW;IAEtB,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IAKxC,OAAO,CAAC,cAAc,CAAoC;IAK1D,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAoB;gBAGpD,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,iBAAiB,EACzB,MAAM,CAAC,EAAE,MAAM;IAQjB;;;;;;;OAOG;IACG,mBAAmB,CACvB,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,cAAc,EACrB,YAAY,EAAE,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC,GACzC,OAAO,CAAC,IAAI,CAAC;IAMhB;;;OAGG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvE;;;;;OAKG;IACG,UAAU,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7D;;;;;OAKG;IACG,gBAAgB,CACpB,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,WAAW,EAAE,GACpB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;CAGhC"}

package/dist/views/projection-reducers.d.ts

@@ -1,73 +0,0 @@
-/**
- * Projection reducers — the pure core of the system-level projection
- * materializers in `view-materializer.ts`.
- *
- * Each reducer takes the current state of a `__system__` projection and
- * a single command payload, and returns the next state plus any
- * side-effect signals (currently just optional warnings). The
- * surrounding I/O — read JSON file → reduce → write JSON file — lives
- * in the `ViewMaterializer` shell.
- *
- * Why this split: tests for the projection-update semantics shouldn't
- * need the filesystem or an Apple-container event store to assert
- * "registering identical content twice is a no-op." The shell is
- * already covered by integration tests at `tag-schemas-reader.test.ts`
- * (Stower → materializer → reader round-trip) and
- * `local-transport.test.ts` (real client → bus → cache invalidation).
- *
- * The reducers also become the natural home for the deferred schema-
- * evolution work in `.plans/EVOLVE-TAG-SCHEMA.md` — migration
- * commands (rename/remove a category, version-bump a schema id) are
- * additional pure functions on the same view shapes.
- *
- * Load-bearing properties (sortedness, uniqueness, idempotence,
- * most-recent-wins, no-mutation) are pinned by axiom-style fast-check
- * tests in `__tests__/views/projection-reducers.test.ts`. See
- * `docs/system/PROJECTION-PATTERN.md` for the full axiom catalog and
- * the architectural narrative.
- */
-import type { TagSchema } from '@semiont/core';
-/**
- * Apply a `frame:entity-type-added` event to the entity-types
- * projection. Idempotent — dedup via a `Set` + locale-aware sort.
- *
- * Sort uses `localeCompare` to match {@link applyTagSchemaAdded}'s
- * id-sort and to give a sensible ordering across mixed-case + symbol
- * tags. (The pre-refactor materializer used `Array.sort()` with no
- * comparator, which is codepoint order — `_x` would sort *after* `A`
- * because `_` (0x5F) > `A` (0x41). Surfaced by an axiom test in
- * `projection-reducers.test.ts`.)
- */
-export declare function applyEntityTypeAdded(current: readonly string[], add: string): string[];
-/**
- * Result of {@link applyTagSchemaAdded}.
- *
- * The reducer is pure — it doesn't log warnings itself. Instead it
- * returns the would-be warning as data; the I/O shell decides whether
- * to forward it to the logger. This keeps the function trivially
- * testable and lets callers compose multiple reductions without
- * threading a logger through.
- */
-export interface ApplyTagSchemaAddedResult {
-    /** The next state of the tagSchemas list, sorted by id. */
-    next: TagSchema[];
-    /**
-     * Set when an existing schema with the same id was overwritten with
-     * differing content (deep-not-equal). Identical re-registrations
-     * return `undefined` here — the projection silently no-ops.
-     */
-    warning?: {
-        schemaId: string;
-        message: string;
-    };
-}
-/**
- * Apply a `frame:tag-schema-added` event to the tag-schemas projection.
- *
- * Most-recent-wins by `schema.id`:
- *  - new id → append + sort
- *  - existing id with identical content → no-op (warning undefined)
- *  - existing id with differing content → replace + warning emitted
- */
-export declare function applyTagSchemaAdded(current: readonly TagSchema[], add: TagSchema): ApplyTagSchemaAddedResult;
-//# sourceMappingURL=projection-reducers.d.ts.map

package/dist/views/projection-reducers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"projection-reducers.d.ts","sourceRoot":"","sources":["../../src/views/projection-reducers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAI/C;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,GAAG,EAAE,MAAM,GACV,MAAM,EAAE,CAIV;AAID;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAAyB;IACxC,2DAA2D;IAC3D,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,SAAS,EAAE,EAC7B,GAAG,EAAE,SAAS,GACb,yBAAyB,CAqB3B"}