@semiont/event-sourcing 0.5.4 → 0.5.5

package/dist/index.d.ts

@@ -1,25 +1,650 @@
+import * as _semiont_core from '@semiont/core';
+import { ResourceId, ResourceDescriptor, ResourceAnnotations, Logger, EventInput, StoredEvent, EventQuery as EventQuery$1, PersistedEvent, EventBus, TagSchema } from '@semiont/core';
+import { SemiontProject } from '@semiont/core/node';
+
 /**
- * @semiont/event-sourcing
+ * View Storage - Materialized Views
  *
- * Event sourcing infrastructure for Semiont
+ * Stores materialized views of resource state and annotations
+ * Built from event streams, can be rebuilt at any time
  *
- * Provides:
- * - EventStore: Orchestration layer for event sourcing
+ * 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[]>;
+}
+
+/**
+ * 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 / materializeTagSchemas) is unchanged and runs in
+     * addition.
+     */
+    rebuildAll(eventLog: RebuildEventSource): Promise<void>;
+    /**
+     * Materialize entity types view — System-level view.
+     *
+     * I/O shell around the pure {@link applyEntityTypeAdded} reducer:
+     * read JSON file → reduce → write JSON file. The reducer owns the
+     * dedup + sort semantics; the shell owns the disk I/O.
+     */
+    materializeEntityTypes(entityType: string): Promise<void>;
+    /**
+     * Materialize tag schemas view — System-level view.
+     *
+     * I/O shell around the pure {@link applyTagSchemaAdded} reducer.
+     * The reducer owns the most-recent-wins semantics + the
+     * differing-content-overwrite-warning; the shell forwards the
+     * warning (when present) to this materializer's logger and writes
+     * the resulting state to disk.
+     */
+    materializeTagSchemas(schema: _semiont_core.TagSchema): 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 (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>;
+}
+
+/**
+ * EventStore - Orchestration Layer
+ *
+ * Coordinates event sourcing operations:
  * - EventLog: Event persistence (append, retrieve, query)
  * - ViewManager: View materialization (resource and system)
- * - 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
+ * - 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>;
+}
+
+/**
+ * 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.
+ */
+
+/**
+ * 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`.)
+ */
+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.
+ */
+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
+ */
+declare function applyTagSchemaAdded(current: readonly TagSchema[], add: TagSchema): ApplyTagSchemaAddedResult;
+
+/**
+ * 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 { EventLog, EventQuery, EventStorage, EventStore, FilesystemViewStorage, ResourceNotFoundError, ViewManager, ViewMaterializer, applyEntityTypeAdded, applyTagSchemaAdded, createEventStore, generateAnnotationId, getShardPath, jumpConsistentHash, removeStorageUriEntry, resolveStorageUri, sha256, writeStorageUriEntry };
+export type { ApplyTagSchemaAddedResult, EnrichEvent, EventLogConfig, EventStorageConfig, ResourceView, StorageUriEntry, ViewManagerConfig, ViewStorage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/event-sourcing",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "Event sourcing infrastructure for Semiont - EventLog, EventBus, and ViewManager",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "build": "npm run typecheck && tsup && tsc -p tsconfig.build.json",
+    "build": "npm run typecheck && tsup && tsc -p tsconfig.build.json && rollup -c rollup.dts.config.mjs && rm -rf dist-types",
     "watch": "tsup --watch",
     "clean": "rm -rf dist *.tsbuildinfo",
     "test": "vitest run",
@@ -51,6 +51,8 @@
     "@types/uuid": "^10.0.0",
     "@vitest/coverage-v8": "^4.1.0",
     "fast-check": "^4.3.0",
+    "rollup": "^4.60.3",
+    "rollup-plugin-dts": "^6.4.1",
     "tsup": "^8.5.1",
     "typescript": "^6.0.2"
   },