Review brief

Intermediate30 min

A profile editor now shows submitted values immediately while saves run in the background. Users may submit another revision or keep typing before earlier requests settle, and the API fences a stable editor session by increasing client revision before returning canonicalized values.

Behavioral contract

Every submit starts immediately, receives a unique idempotency key and increasing clientRevision within the stable editorSessionId, and optimistically updates the saved-profile preview; saves may overlap. The API atomically prevents a lower revision from overwriting a higher applied revision, reports applied or superseded with the authoritative profile, and a rejected save is guaranteed not to have committed.
Keep one outcome-ledger entry per submitted revision. Every completion updates only its own entry; derive the preview from the highest revision that is pending or applied, falling back through lower entries and then the initial confirmed profile when newer revisions fail or are superseded.
Pending remains visible while any submitted revision is unfinished. Retain errors with their owning revisions; display the highest failed revision only until a later submission begins, and never let an unrelated completion clear or replace it.
Edits typed after a submission remain in the form draft when that request completes. An applied response may replace the draft only if the draft still exactly equals that revision's submitted snapshot.
Use the stable editor session and client revision to form an idempotency key unique across separate submissions, including submissions started in the same millisecond.

Review instructions

1Trace at least two saves completing in both orders and with both outcomes.
2Anchor each finding to the narrowest useful changed line and explain the visible consequence.
3Recommend a direction rather than writing replacement code.
4Prioritize no more than four findings.

Learning objectives

• Order overlapping optimistic completions
• Rollback without discarding newer state
• Separate server-confirmed state from edits made in flight

src/profile-api.tsTypeScript

@@ -0,0 +1,20 @@

1+export interface Profile {

2+ displayName: string;

3+ biography: string;

4+}

6+export interface ProfileSaveResult {

7+ status: "applied" | "superseded";

8+ canonicalProfile: Profile;

9+}

10+

11+export interface ProfileApi {

12+ save(

13+ profile: Profile,

14+ options: {

15+ editorSessionId: string;

16+ clientRevision: number;

17+ idempotencyKey: string;

18+ },

19+ ): Promise<ProfileSaveResult>;

20+}

Reference solution

The findings below are ordered by priority.

Findings

1. Completions mutate one preview instead of an outcome ledger

Location: src/optimistic-profile-editor.tsx:25-47

requestId is created but no per-revision outcome is retained. Each callback writes directly to savedProfile, so an older success can overwrite a newer optimistic submission and an older failure can restore a stale snapshot. Merely ignoring older completions is also insufficient: if request two fails back to request one's optimistic value and request one later fails, that value would remain displayed even though neither save succeeded.

Store pending, applied, superseded, and failed outcomes by revision and derive the visible preview from that ledger, falling back through lower revisions to the initial confirmed profile. Pass the stable session and increasing revision already supported by the API so a late lower revision cannot overwrite a higher server revision.

2. An old completion clears status owned by a newer request

Location: src/optimistic-profile-editor.tsx:41-47

Both branches unconditionally clear pending, and the failure branch replaces one shared error. If request one settles while request two is still pending, the editor claims all saving is finished or displays a failure without retaining which revision owns it.

Derive pending from whether any ledger entry remains unfinished. Retain errors with their owning revisions, display the highest failed revision until the next submit, and do not allow an unrelated completion to clear or replace it.

3. A response discards edits typed after submission

Location: src/optimistic-profile-editor.tsx:39-42

Every applied or superseded response replaces draft with the returned canonical profile. If the user edits the biography while the request is in flight, those unsaved keystrokes disappear.

Record the response in its ledger entry, but replace the form draft only when it still field-for-field matches that revision's submitted snapshot; otherwise preserve the newer draft.

4. Millisecond timestamps are not unique idempotency keys

Location: src/optimistic-profile-editor.tsx:34-38

Two separate submissions started during the same millisecond receive the same key. A backend deduplicating by that key can treat the second profile revision as a retry of the first and never persist it.

Derive the key from the stable editorSessionId and monotonically increasing clientRevision already sent to the API.

Reasonable non-findings

Starting a later save without disabling the button is required by the overlap contract.
Copying draft into submitted prevents later controlled-input updates from mutating that request payload.
Functional draft updates correctly preserve the sibling field.
Rendering the error with role="alert" is appropriate for the latest save failure once completion ownership is fixed.