suaveplan/openspec/archive/2026-04-24-enterprise-event-sourcing/tasks.md

Tasks: enterprise-event-sourcing

• Change ID: enterprise-event-sourcing
• Package: @suaveplan/event-sourcing
• Date: 2026-04-24

Prerequisites (must be published to Verdaccio first)

• @suaveplan/events
• @suaveplan/diff
• @suaveplan/error
• @suaveplan/types

Tasks

1. Scaffold package

• Create universal/events/event-sourcing/ directory tree per file layout in proposal.md
• Write package.json (name @suaveplan/event-sourcing, version 0.1.0, sideEffects: false, correct workspace deps and catalog externals)
• Write tsconfig.json extending @suaveplan/typescript-config/library.json
• Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config

2. Error codes (src/error-codes.ts)

• Define EventSourcingErrorCode union type
• Call defineCodes to register all ES.* codes
• Export registerEventSourcingErrorCodes() and EventSourcingError

3. Types (src/types/common.ts)

• Define and export DomainEvent<T>, EventMetadata, Snapshot, EventStore, AggregateRepositoryOptions
• Write common.md

4. Aggregate base class (src/core/aggregate/)

• Implement abstract Aggregate<TState> with raise, apply (abstract), replayFrom, clearPendingEvents, pendingEvents, version, id
• Write .md, .types.ts, .test.ts, index.ts

5. EventStore interface (src/core/event-store/)

• Define and export EventStore interface with append, load, loadSnapshot, saveSnapshot, getStream
• Write .md, .types.ts, index.ts

6. In-memory event store (src/core/memory-event-store/)

• Implement createMemoryEventStore with:
  • Per-aggregate stream storage (Map of arrays)
  • Optimistic concurrency: append checks expectedVersion and throws ES_CONCURRENCY_CONFLICT on mismatch
  • Snapshot storage alongside event streams
  • Publish committed events to @suaveplan/events bus after successful append
  • Optional delta-payload compression via @suaveplan/diff when deltaPayloads: true
  • OTel spans, counters, histograms per proposal.md §5
• Write .md, .types.ts, .test.ts, index.ts

7. Aggregate repository (src/core/aggregate-repository/)

• Implement createAggregateRepository<T> with snapshot-based reconstruction
• Optimistic concurrency retry loop (configurable maxRetries)
• Auto-snapshot at configurable snapshotThreshold
• Write .md, .types.ts, .test.ts, index.ts

8. Projection builder (src/projection/projection-builder/)

• Implement createProjection<TState> with project(events) and projectStream(stream) methods
• Write .md, .types.ts, .test.ts, index.ts

9. Upcaster registry (src/upcasting/upcaster/)

• Implement registerUpcaster and upcastEvents with version-ordered upcaster chain
• Write .md, .types.ts, .test.ts, index.ts

10. Tests

• Unit tests co-located (100% coverage target)
• tests/integration.test.ts — full aggregate lifecycle: create, load, save with snapshot, reload from snapshot + trailing events
• tests/property.test.ts — fast-check properties per proposal.md §6

11. Benchmarks (src/__benchmarks__/event-sourcing.bench.ts)

• Implement benchmark cases per proposal.md §7

12. Docs

• Every .ts implementation file has a sibling .md
• Root README.md

13. Pre-publish gate

• bunx turbo lint typecheck test --filter=@suaveplan/event-sourcing green
• bunx turbo test:coverage --filter=@suaveplan/event-sourcing ≥ 100% on touched modules

14. Publish

• bun scripts/publish.ts --package @suaveplan/event-sourcing

15. Archive

• Fold spec delta into openspec/specs/events/spec.md
• mv openspec/changes/enterprise-event-sourcing openspec/archive/2026-04-24-enterprise-event-sourcing