# Tasks: enterprise-event-sourcing

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

## Prerequisites (must be published to Verdaccio first)

- [x] `@suaveplan/events`
- [x] `@suaveplan/diff`
- [x] `@suaveplan/error`
- [x] `@suaveplan/types`

## Tasks

### 1. Scaffold package

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

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

- [x] Define `EventSourcingErrorCode` union type
- [x] Call `defineCodes` to register all `ES.*` codes
- [x] Export `registerEventSourcingErrorCodes()` and `EventSourcingError`

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

- [x] Define and export `DomainEvent<T>`, `EventMetadata`, `Snapshot`, `EventStore`, `AggregateRepositoryOptions`
- [x] Write `common.md`

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

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

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

- [x] Define and export `EventStore` interface with `append`, `load`, `loadSnapshot`, `saveSnapshot`, `getStream`
- [x] Write `.md`, `.types.ts`, `index.ts`

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

- [x] 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
- [x] Write `.md`, `.types.ts`, `.test.ts`, `index.ts`

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

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

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

- [x] Implement `createProjection<TState>` with `project(events)` and `projectStream(stream)` methods
- [x] Write `.md`, `.types.ts`, `.test.ts`, `index.ts`

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

- [x] Implement `registerUpcaster` and `upcastEvents` with version-ordered upcaster chain
- [x] Write `.md`, `.types.ts`, `.test.ts`, `index.ts`

### 10. Tests

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

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

- [x] Implement benchmark cases per `proposal.md` §7

### 12. Docs

- [x] Every `.ts` implementation file has a sibling `.md`
- [x] Root `README.md`

### 13. Pre-publish gate

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

### 14. Publish

- [x] `bun scripts/publish.ts --package @suaveplan/event-sourcing`

### 15. Archive

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