Order a review's timeline by attempt, because ULIDs are a coin flip

CI failed on a test that passes here: the checkpointing runner's record of a
call that answered and then died. Chasing it found a real ordering bug rather
than a flaky test.

Every row a single call writes shares one startedAt, and the timeline was
ordered by (startedAt, id) with ULID ids as the tiebreak. ULIDs are not
monotonic inside a millisecond. Measured over twenty thousand pairs, the second
of two generated in the same millisecond sorts before the first 9,594 times out
of 19,198, so one call's rows came back in a random order and the assertion
about which row held the usage was a coin flip.

Ordering is by attempt within a timestamp now, which is what the sequence
actually is. A test pins it, and reproducing the old ordering fails that test in
eight runs out of twelve, which is the honest shape of the bug: frequent enough
that CI caught it, rare enough that twelve local runs of the original test did
not.

Worth recording rather than just fixing, because the same trap applies anywhere
a ULID is used to break a tie inside one timestamp.

Author: Poolchaos

docs/DECISIONS.md

@@ -778,3 +778,12 @@ verified evidence, in writing, here.
 - 2026-07-31 DECIDED (V7, D-44): the new-review screen links to the ruleset
   page rather than opening a drawer. At one screen of this size a drawer
   duplicates a page that already exists.
+- 2026-07-31 FIXED: the stage timeline was ordered by (startedAt, id), and
+  every row a single call writes shares one startedAt. ULIDs are not monotonic
+  within a millisecond: measured over twenty thousand pairs, the second of two
+  generated in the same millisecond sorts before the first 9,594 times out of
+  19,198, so one call's rows came back in a random order. It surfaced as a test
+  that passed locally and failed in CI. Ordering is now by attempt within a
+  timestamp, which is the real sequence, and a test reproducing the old
+  ordering fails it about two runs in three. Recorded because the same trap
+  applies anywhere else ULIDs are used as a tiebreak within one timestamp.

src/server/db/repositories/stage-executions.ts

@@ -125,13 +125,23 @@ export function latestChainedSession(db: Db, reviewId: string): string | undefin
   );
 }
 
-/** Everything this review has asked, oldest first, for the timeline. */
+/**
+ * Everything this review has asked, oldest first, for the timeline.
+ *
+ * Ordered by attempt within a timestamp, not by id. Every row a single call
+ * writes shares one startedAt, and ULIDs are not monotonic inside a
+ * millisecond: measured over twenty thousand pairs, the second of two ids
+ * generated in the same millisecond sorts before the first almost exactly half
+ * the time. Ordering by id therefore returned one call's rows in a random
+ * order, which showed up as a test that passed here and failed in CI. Attempt
+ * numbers are the real sequence, so they are what the sequence is read from.
+ */
 export function listForReview(db: Db, reviewId: string): StageExecution[] {
   return db
     .select()
     .from(stageExecutions)
     .where(eq(stageExecutions.reviewId, reviewId))
-    .orderBy(asc(stageExecutions.startedAt), asc(stageExecutions.id))
+    .orderBy(asc(stageExecutions.startedAt), asc(stageExecutions.attempt), asc(stageExecutions.id))
     .all();
 }
 

tests/server/db/stage-executions.test.ts

@@ -274,3 +274,26 @@ describe("the record of what a review spent", () => {
     expect(listForReview(db, reviewId)).toEqual([]);
   });
 });
+
+describe("the order a timeline reads in", () => {
+  it("keeps one call's rows in attempt order, whatever their ids sort like", () => {
+    // Every row a single call writes shares one startedAt, and ULIDs are not
+    // monotonic inside a millisecond: the second of two generated in the same
+    // millisecond sorts before the first about half the time. Ordering by id
+    // returned them at random, which passed locally and failed in CI.
+    const startedAt = "2026-07-31T10:00:00.000Z";
+    for (const attempt of [1, 2, 3]) {
+      recordAttempt(db, {
+        reviewId,
+        stage: "s1_risk",
+        promptHash: "same-question",
+        attempt,
+        status: attempt === 3 ? "failed" : "succeeded",
+        outputJson: attempt === 3 ? null : "{}",
+        startedAt,
+      });
+    }
+
+    expect(listForReview(db, reviewId).map((row) => row.attempt)).toEqual([1, 2, 3]);
+  });
+});