@semiont/event-sourcing 0.5.2 → 0.5.4

package/README.md

@@ -136,6 +136,17 @@ await eventStore.views.rebuildAll(eventStore.log);
 
 The two paths use the same materialization primitives, so replaying event 1..N via `rebuildAll` produces the same final state as the live path walking 1..N over time.
 
+#### Pure projection reducers
+
+The `__system__` projections (`entitytypes.json`, `tagschemas.json`) are written by a thin I/O shell wrapping pure functions that own the merge/dedup/sort/conflict semantics. The pure reducers live in [`src/views/projection-reducers.ts`](src/views/projection-reducers.ts):
+
+- `applyEntityTypeAdded(view, tag)` → `string[]` — dedup + locale-aware sort.
+- `applyTagSchemaAdded(view, schema)` → `{ next; warning? }` — most-recent-wins by id, warning on overwrite-with-different-content.
+
+The shell methods on `ViewMaterializer` (`materializeEntityTypes`, `materializeTagSchemas`) read the projection file, call the reducer, then write the result. The semantics are the reducer's; the disk I/O is the shell's.
+
+This split keeps projection-update tests pure (single-digit milliseconds, no filesystem) and gives load-bearing invariants — sortedness, uniqueness, idempotence, most-recent-wins — a property-based-test home using fast-check. The full architectural narrative, the axiom catalog, and guidance for adding new projections lives in [`docs/system/PROJECTION-PATTERN.md`](../../docs/system/PROJECTION-PATTERN.md).
+
 #### Why startup rebuild exists
 
 The materialized views directory (`stateDir`) is **ephemeral by design** — it's safe to wipe (container recreation, `semiont destroy`, dev cleanup), and the event log under `.semiont/events/` is the single source of truth. `rebuildAll` is what makes "ephemeral" safe: any time `stateDir` goes empty, the next process start repopulates it from the event log.

package/dist/event-log.d.ts

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

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

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

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

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

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

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

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