suaveplan/openspec/changes/event-sourcing-completion/tasks.md

Tasks — Event-sourcing completion

Every checkbox MUST reflect work actually done in this change. The seven capabilities closed here were silently dropped during the original genesis migration (audit dated 2026-05-02). Do not retroactively tick boxes for surface that already shipped.

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Spec authoring

• 1.1 Read ../suaveplan/packages/universal/event-sourcing/src/{outbox,store,replay,subscription,snapshot,versioning,event-sourcing-events}.ts end-to-end
• 1.2 Read openspec/specs/event-sourcing/spec.md (if it exists; create the cap dir if not)
• 1.3 Read openspec/AGENTS.md Sections 0a (parity), 13 (spec-conformance), 14 (source mapping), 14a (dependents)
• 1.4 Draft proposal.md covering all seven gaps (EventOutbox, DatabaseEventStore, DatabaseSnapshotStore, EventReplayer, EventBus + SubscriptionFilter, SnapshotManager, UpcasterChain)
• 1.5 Fill ## Source mapping in proposal.md with upstream line ranges for every requirement; every "no source line" requirement justified
• 1.6 Draft spec delta at specs/event-sourcing/spec.md
• 1.7 Every requirement in the spec delta carries a **Verified by:** line naming concrete it(...) titles
• 1.8 openspec change validate event-sourcing-completion exits with no errors

2. Implementation

• 2.1 EventOutbox interface + MemoryEventOutbox class — port from upstream outbox/outbox-pattern.ts into packages/events/event-sourcing/src/outbox/event-outbox.ts (interface) and packages/events/event-sourcing/src/outbox/memory-outbox.ts (impl)
• 2.2 OutboxRelay worker — extract relay loop into a standalone class with injectable Clock and AbortSignal; new file packages/events/event-sourcing/src/outbox/relay.ts
• 2.3 DatabaseEventStore<TEvent> — port from upstream store/database-event-store.ts into packages/events/event-sourcing/src/store/database-event-store.ts; replace EventStoreDatabaseAdapter with DatabaseAdapter from @suaveplan/db
• 2.4 DatabaseSnapshotStore<TState> — port from upstream store/database-snapshot-store.ts into packages/events/event-sourcing/src/store/database-snapshot-store.ts; add serializer / deserializer config hooks
• 2.5 EventReplayer — port from upstream replay/event-replayer.ts into packages/events/event-sourcing/src/replay/event-replayer.ts; thread AbortSignal through replay, replayByType, replayEvents
• 2.6 EventBus + SubscriptionFilter — port from upstream subscription/event-subscription.ts into packages/events/event-sourcing/src/subscription/event-bus.ts; replace module-scope counter with injectable IdGenerator
• 2.7 DeadLetterSink interface + MemoryDeadLetterSink — new file packages/events/event-sourcing/src/subscription/dead-letter.ts; capture handler exceptions during EventBus.publish
• 2.8 SnapshotManager<TState> — port from upstream snapshot/snapshot-manager.ts into packages/events/event-sourcing/src/snapshot/snapshot-manager.ts; replace new Date() with injectable Clock
• 2.9 UpcasterChain ordered registry — port from upstream versioning/event-upcaster.ts into packages/events/event-sourcing/src/upcasting/chain.ts
• 2.10 detectSchemaVersion, createUpcastedEvent, createRenamedEvent helpers — co-locate next to UpcasterChain
• 2.11 createFieldRenameUpcaster, createDefaultFieldUpcaster, createRemoveFieldUpcaster builders — co-locate next to UpcasterChain
• 2.12 Wire legacy registerUpcaster / clearUpcasters / upcastEvents to delegate to a module-scoped UpcasterChain so both APIs share one registry
• 2.13 Add ES_* codes (OUTBOX_TABLE_INIT_FAILED, OUTBOX_PUBLISH_FAILED, OUTBOX_RELAY_INTERRUPTED, EVENT_INVALID, EVENT_HANDLER_FAILED, REPLAY_CANCELLED, REPLAY_FILTER_INVALID, SUBSCRIPTION_INVALID, DATABASE_TABLE_INIT_FAILED, SNAPSHOT_HANDLER_FAILED, UPCASTER_DUPLICATE) to errors/event-sourcing-error.ts
• 2.14 Wire OTel counters / spans on every public entrypoint: outbox.relayed, outbox.failed, outbox.pending_size, database.events_appended, database.snapshots_saved, replay.events_processed, replay.duration_ms, subscription.published, subscription.dead_lettered, snapshot.created, snapshot.pruned, upcaster.applied, upcaster.skipped
• 2.15 Wire Zod schemas for OutboxConfig, DatabaseEventStoreConfig, DatabaseSnapshotStoreConfig, ReplayFilter, ReplayConfig, SubscriptionOptions, SubscriptionFilter, SnapshotManagerConfig, EventUpcaster to schemas/event-sourcing.schemas.ts
• 2.16 Update index.ts barrel — re-export every new symbol; no export * (one explicit subpath per module)
• 2.17 Update package.json exports map — add subpaths ./outbox/event-outbox, ./outbox/memory-outbox, ./outbox/relay, ./store/database-event-store, ./store/database-snapshot-store, ./replay/event-replayer, ./subscription/event-bus, ./subscription/dead-letter, ./snapshot/snapshot-manager, ./upcasting/chain
• 2.18 Update package.json dependencies — add @suaveplan/db (workspace:^)

3. Tests

• 3.1 packages/events/event-sourcing/src/outbox/event-outbox.test.ts — interface contract; MemoryEventOutbox insertion order; per-row attempts counter; pendingCount / failedCount / cleanup
• 3.2 packages/events/event-sourcing/src/outbox/event-outbox.spec-conformance.test.ts — Zod-rejected configs emit OUTBOX_TABLE_INIT_FAILED; injected IdGenerator deterministic; OTel counter outbox.pending_size
• 3.3 packages/events/event-sourcing/src/outbox/relay.test.ts — successful relay marks rows published; failure increments attempts; AbortSignal aborts in-flight loops with OUTBOX_RELAY_INTERRUPTED; injected Clock deterministic
• 3.4 packages/events/event-sourcing/src/store/database-event-store.test.ts — append + load round-trip; optimistic-concurrency conflict raises CONCURRENCY_CONFLICT; getEventsByType honours limit; count() returns total
• 3.5 packages/events/event-sourcing/src/store/database-event-store.spec-conformance.test.ts — table auto-create gated on autoCreate: true; transaction() rollback on adapter exception; emits event:appended lifecycle event
• 3.6 packages/events/event-sourcing/src/store/database-snapshot-store.test.ts — save / load latest-per-aggregate; configurable serializer round-trips a non-JSON state; delete returns false for unknown aggregate; getInterval returns config
• 3.7 packages/events/event-sourcing/src/replay/event-replayer.test.ts — full replay invokes handler in stream order; filter narrows by eventTypes / aggregateId / fromDate / toDate; pause / resume / cancel / reset state machine; onProgress final tick has completed: true; batch size honoured
• 3.8 packages/events/event-sourcing/src/replay/event-replayer.spec-conformance.test.ts — abort signal mid-batch rejects with REPLAY_CANCELLED; bad filter rejected with REPLAY_FILTER_INVALID; OTel histogram replay.duration_ms
• 3.9 packages/events/event-sourcing/src/subscription/event-bus.test.ts — subscribe / publish round-trip; filter narrows by eventTypes / aggregateIds / aggregateType; group round-robin distribution; unsubscribe removes record; subscriberCount reflects active subscriptions
• 3.10 packages/events/event-sourcing/src/subscription/event-bus.spec-conformance.test.ts — handler exceptions route to DeadLetterSink with EVENT_HANDLER_FAILED cause; injected IdGenerator produces deterministic subscription IDs; clear() resets groupCounters
• 3.11 packages/events/event-sourcing/src/subscription/dead-letter.test.ts — MemoryDeadLetterSink capture; iteration order; clear() resets; getEntries() snapshot is immutable
• 3.12 packages/events/event-sourcing/src/snapshot/snapshot-manager.test.ts — load rebuilds from snapshot + tail events; auto-create at interval; pruning at maxSnapshots; shouldCreateSnapshot predicate; getSnapshotHistory per aggregate
• 3.13 packages/events/event-sourcing/src/snapshot/snapshot-manager.spec-conformance.test.ts — injected Clock stamps takenAt deterministically; aggregate:loaded lifecycle event carries restoredFromSnapshot; reducer exception raises SNAPSHOT_HANDLER_FAILED
• 3.14 packages/events/event-sourcing/src/upcasting/chain.test.ts — register orders by fromVersion; upcast walks chain v1→v2→v3; getUpcastersForType filters; clear() empties registry; hasUpcast predicate
• 3.15 packages/events/event-sourcing/src/upcasting/chain.spec-conformance.test.ts — detectSchemaVersion defaults to 1; duplicate (eventType, fromVersion) registration raises UPCASTER_DUPLICATE; createFieldRenameUpcaster / createDefaultFieldUpcaster / createRemoveFieldUpcaster round-trip
• 3.16 Cross-package tests/dep-graph.test.ts — @suaveplan/event-sourcing declares @suaveplan/db as a runtime dep; the package still has zero browser-only deps
• 3.17 Every it(...) carries { timeout: 5000 } (or 30000 for genuinely-async DB-adapter integration)

4. Documentation

• 4.1 Sibling .md for every new implementation .ts (≥200 words, basic + advanced examples, full API reference) — outbox/event-outbox.md, outbox/memory-outbox.md, outbox/relay.md, store/database-event-store.md, store/database-snapshot-store.md, replay/event-replayer.md, subscription/event-bus.md, subscription/dead-letter.md, snapshot/snapshot-manager.md, upcasting/chain.md
• 4.2 README links every co-located .md under ## Modules
• 4.3 Update CLAUDE.md event-sourcing package listing — remove "only Aggregate / aggregate-repository / MemoryEventStore / Projection / flat upcaster" wording; describe the full restored surface
• 4.4 Refresh STATUS.md "Completed on genesis" entry for event-sourcing to reflect parity

5. Pre-archive verification (the 5-gate triple)

• 5.1 bun run check — Biome 0 errors / 0 warnings / 0 info across the monorepo
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/event-sourcing — green
• 5.3 bunx turbo test:coverage --filter=@suaveplan/event-sourcing — 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/event-sourcing — exit 0, no error findings
• 5.5 bunx turbo build --filter=@suaveplan/event-sourcing — green
• 5.6 Banned-pattern scan zero output: grep -rn "@deprecated\|TODO\|FIXME\|ts-ignore\|ts-expect-error\|\.skip\|\.only" packages/events/event-sourcing/src/ --include="*.ts"
• 5.7 Missing .md scan zero output (per AGENTS.md §13 step 5)
• 5.8 README check test -f packages/events/event-sourcing/README.md
• 5.9 Bare-version check zero output (per AGENTS.md §13 step 7)
• 5.10 Subpath count matches feature module count (per AGENTS.md §13 step 8)

6. Pre-archive 7-row checklist (AGENTS.md Section 13)

• 6.1 Generics threaded; expectTypeOf assertions on every literal-type claim (especially DatabaseEventStore<TEvent>, DatabaseSnapshotStore<TState>, SnapshotManager<TState>)
• 6.2 Zod schemas wired at every declared boundary (OutboxConfig, DatabaseEventStoreConfig, DatabaseSnapshotStoreConfig, ReplayFilter, ReplayConfig, SubscriptionOptions, SubscriptionFilter, SnapshotManagerConfig, EventUpcaster)
• 6.3 Every error code added in §2.13 thrown by at least one production code path; no orphans
• 6.4 Strict-mode behaviors tested both on and off (e.g. autoCreate: true vs false; paused vs running replay; cancel() vs reset())
• 6.5 OTel counters / histograms emitted from production paths and asserted with a real in-memory MeterProvider
• 6.6 Lifecycle dedup tested where claimed (SnapshotManager.shouldCreateSnapshot idempotent on identical inputs; EventBus.unsubscribe() on already-unsubscribed record is a no-op)
• 6.7 No retroactive tick — every box above reflects work done in this change

7. Archive

• 7.1 Fold spec delta into openspec/specs/event-sourcing/spec.md (creating the cap file if missing)
• 7.2 Move openspec/changes/event-sourcing-completion/ → openspec/archive/<yyyy-mm-dd>-event-sourcing-completion/
• 7.3 Refresh MANIFEST.md (dep set changed: @suaveplan/event-sourcing now depends on @suaveplan/db)
• 7.4 Update STATUS.md to mark the seven dropped capabilities as restored

Audit Note (2026-05-02)

Audit verdict: DEFERRED — 0/68 tasks evidenced in code.

Evidence reviewed:

• packages/events/event-sourcing/src/ contains core/{aggregate,event-store,aggregate-repository}/, projection/builder/, upcasting/upcaster/, errors/, schemas/, types/, constants/. No outbox/, no replay/, no subscription/, no snapshot/, no store/database-*.
• package.json does not declare @suaveplan/db as a runtime dep (the DatabaseEventStore and DatabaseSnapshotStore need it).
• No new ES_* error codes (OUTBOX_*, REPLAY_*, SUBSCRIPTION_*, SNAPSHOT_HANDLER_FAILED, UPCASTER_DUPLICATE, EVENT_HANDLER_FAILED, etc.) in errors/event-sourcing-error.ts.
• Existing upcasting/upcaster/ is a single class — no UpcasterChain ordered registry, no createFieldRenameUpcaster / createDefaultFieldUpcaster / createRemoveFieldUpcaster builders.

Missing pieces:

1. Outbox subsystem (EventOutbox interface, MemoryEventOutbox, OutboxRelay worker with injectable Clock + AbortSignal).
2. DatabaseEventStore<TEvent> + DatabaseSnapshotStore<TState> (requires adding @suaveplan/db dep).
3. EventReplayer (with pause/resume/cancel/reset state machine) + EventBus with SubscriptionFilter + MemoryDeadLetterSink + SnapshotManager<TState> + UpcasterChain ordered registry.

Decision: leave change open. Seven dropped capabilities, ten new subpath exports, eleven new error codes, dep graph change — all blocked behind real implementation work.