Review an event-sourced account projection

Review exercise · TypeScript

Review brief

Nightmare60 min

An account service projects an ordered event stream into a read model. Delivery is at least once, account events carry contiguous per-account sequences, and operators must rebuild without making the live projection partial.

Behavioral contract

Offsets are globally ordered, delivery is at least once, and each eventId is applied at most once in the same transaction as row and checkpoint changes.
For each account, sequence must equal currentSequence + 1; a duplicate event is ignored only by eventId, while a gap or conflicting sequence stops the partition without advancing its checkpoint.
Balances remain integer cents. Deposits add amountCents, and account opening starts at zero.
An unknown or invalid event is quarantined and stops that partition at its prior checkpoint for operator action; later events cannot pass it.
Rebuild writes to an empty shadow projection with its own checkpoint, validates it, then atomically swaps it into service; readers never observe empty or partial live state.

Review instructions

1Trace normal, duplicate, gap, poison, crash, and rebuild executions.
2Separate transactional root causes from downstream symptoms when combining findings.
3Prioritize no more than six findings.

Learning objectives

• Commit projection state and checkpoints atomically
• Enforce event identity and aggregate sequence invariants
• Rebuild through an isolated projection and atomic cutover

src/account-event-types.tsTypeScript

@@ -0,0 +1,24 @@

1+export interface AccountEvent {

2+ eventId: string;

3+ offset: string;

4+ accountId: string;

5+ sequence: number;

6+ type: "account-opened" | "money-deposited";

7+ amountCents?: number;

8+}

10+export interface AccountProjectionRow {

11+ accountId: string;

12+ sequence: number;

13+ balanceDollars: number;

14+}

15+

16+export interface ProjectionStore {

17+ checkpoint(name: string): Promise<string | undefined>;

18+ saveCheckpoint(name: string, offset: string): Promise<void>;

19+ get(name: string, accountId: string): Promise<AccountProjectionRow | undefined>;

20+ put(name: string, row: AccountProjectionRow): Promise<void>;

21+ clear(name: string): Promise<void>;

22+ swap(source: string, destination: string): Promise<void>;

23+ quarantine(event: AccountEvent, error: unknown): Promise<void>;

24+}

Reference solution

The findings below are ordered by priority.

Findings

1. The checkpoint commits before the projected row

Location: src/account-projector.ts:7-10

The offset is saved before any row read or write and not in one transaction with them. A crash or write failure leaves the checkpoint past an unapplied event, so restart permanently skips required state.

Apply event identity, row mutation, and checkpoint advance atomically, with the checkpoint last in the logical transaction.

2. Duplicate event IDs are applied again

Location: src/account-projector.ts:10-29

No durable event-ID ledger or uniqueness claim exists. At-least-once redelivery of a deposit adds its amount again, and redelivery of an opening event can reset an existing balance.

Claim eventId in the projection transaction and treat only that exact duplicate as already applied.

3. Aggregate sequence ordering is never enforced

Location: src/account-projector.ts:10-27

The projector writes whatever sequence arrives without requiring current.sequence + 1. A gap can skip account history, while an older event can overwrite the sequence and corrupt later calculations.

Lock or compare-and-swap the account row and reject any non-duplicate event whose sequence is not exactly next, leaving the checkpoint unchanged.

4. Balances use fractional dollars instead of integer cents

Location: src/account-event-types.ts:10-13, src/account-projector.ts:21-26

The read model stores balanceDollars and repeatedly divides integer cents into binary floating-point values. Repeated additions can accumulate representation error and the schema violates the cents invariant.

Store and add integer balanceCents without conversion.

5. Invalid and failed events do not block the partition safely

Location: src/account-projector.ts:8-30

There is no validation for a missing deposit amount or a runtime-unknown type, so those inputs become a zero deposit or no-op after checkpoint advance. When a store operation does throw, the catch records it but resolves normally. In both cases the stream can continue past poison history.

Validate before applying, quarantine any invalid or failed event while retaining the prior checkpoint, then surface a controlled partition-stopping failure.

6. Rebuild destroys and exposes the live projection in place

Location: src/rebuild-account-projection.ts:7-10

The rebuild clears accounts-live and repopulates it row by row. Readers see empty or partial state, and a mid-rebuild failure leaves production permanently incomplete.

Replay into an empty shadow name with independent idempotency and checkpoint state, validate it, then atomically swap it into the live name.

Reasonable non-findings

Processing the supplied stream sequentially is appropriate for an ordered partition.
Account opening at zero and deposits as additions match the event semantics.
Quarantine is a valid operator tool when it blocks progress rather than silently bypassing history.