@semiont/event-sourcing 0.5.2 → 0.5.4

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

@@ -0,0 +1,111 @@
+/**
+ * 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

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

@@ -0,0 +1,56 @@
+/**
+ * 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

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

@@ -0,0 +1,60 @@
+/**
+ * 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

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

@@ -0,0 +1,33 @@
+/**
+ * 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

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

@@ -0,0 +1,84 @@
+/**
+ * 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

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

@@ -0,0 +1,73 @@
+/**
+ * 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

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

package/dist/views/view-materializer.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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
+ */
+import type { PersistedEvent, StoredEvent, ResourceId, Logger } from '@semiont/core';
+import type { ViewStorage, ResourceView } from '../storage/view-storage';
+/**
+ * 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.
+ */
+export interface RebuildEventSource {
+    getEvents(resourceId: ResourceId): Promise<StoredEvent[]>;
+    getAllResourceIds(): Promise<ResourceId[]>;
+}
+export interface ViewMaterializerConfig {
+    basePath: string;
+}
+/**
+ * ViewMaterializer builds and maintains materialized views from events
+ */
+export 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: import('@semiont/core').TagSchema): Promise<void>;
+}
+//# sourceMappingURL=view-materializer.d.ts.map

package/dist/views/view-materializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-materializer.d.ts","sourceRoot":"","sources":["../../src/views/view-materializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EAEX,UAAU,EACV,MAAM,EACP,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAGzE;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC1D,iBAAiB,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAIzB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,MAAM;IAJhB,OAAO,CAAC,MAAM,CAAC,CAAS;gBAGd,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,sBAAsB,EACtC,MAAM,CAAC,EAAE,MAAM;IAKjB;;;OAGG;IACG,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAkB9F;;;OAGG;IACG,sBAAsB,CAC1B,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,cAAc,EACrB,YAAY,EAAE,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC,GACzC,OAAO,CAAC,IAAI,CAAC;IA4BhB;;;;;OAKG;YACW,0BAA0B;IAYxC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAiC7B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA0I5B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA6E/B;;;;;;;;;OASG;IACG,UAAU,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAqD7D;;;;;;OAMG;IACG,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB/D;;;;;;;;OAQG;IACG,qBAAqB,CAAC,MAAM,EAAE,OAAO,eAAe,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;CA4BtF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/event-sourcing",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "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",
+    "build": "npm run typecheck && tsup && tsc -p tsconfig.build.json",
     "watch": "tsup --watch",
     "clean": "rm -rf dist *.tsbuildinfo",
     "test": "vitest run",
@@ -50,8 +50,9 @@
   "devDependencies": {
     "@types/uuid": "^10.0.0",
     "@vitest/coverage-v8": "^4.1.0",
+    "fast-check": "^4.3.0",
     "tsup": "^8.5.1",
-    "typescript": "^5.6.3"
+    "typescript": "^6.0.2"
   },
   "dependencies": {
     "@semiont/api-client": "*",