refactor(api): move RandomSource to shared and add rollInclusive

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

apps/api/src/shared/random-source.ts

@@ -0,0 +1,9 @@
+export interface RandomSource {
+  next(): number; // uniform value in [0, 1)
+}
+
+export const RANDOM_SOURCE = Symbol('RANDOM_SOURCE');
+
+export const systemRandomSource: RandomSource = {
+  next: () => Math.random(),
+};

apps/api/src/shared/roll-range.spec.ts

@@ -0,0 +1,28 @@
+import type { RandomSource } from './random-source';
+import { rollInclusive } from './roll-range';
+
+function fixed(...values: number[]): RandomSource {
+  let index = 0;
+  return { next: () => values[index++] };
+}
+
+describe('rollInclusive', () => {
+  it('maps the bottom of the random range to min and the top to max', () => {
+    expect(rollInclusive(fixed(0), 4, 7)).toBe(4);
+    expect(rollInclusive(fixed(0.999), 4, 7)).toBe(7);
+  });
+
+  it('spreads the random range evenly across every value in between', () => {
+    expect(rollInclusive(fixed(0.25), 4, 7)).toBe(5);
+    expect(rollInclusive(fixed(0.5), 4, 7)).toBe(6);
+    expect(rollInclusive(fixed(0.5), 9, 15)).toBe(12);
+  });
+
+  it('never exceeds max even if the source yields exactly 1', () => {
+    expect(rollInclusive(fixed(1), 9, 15)).toBe(15);
+  });
+
+  it('returns the single value when min equals max', () => {
+    expect(rollInclusive(fixed(0.7), 1, 1)).toBe(1);
+  });
+});

apps/api/src/shared/roll-range.ts

@@ -0,0 +1,19 @@
+import type { RandomSource } from './random-source';
+
+/**
+ * Rolls an inclusive integer in [min, max] from one value of `random`.
+ *
+ * `RandomSource.next()` is documented as [0, 1), but the clamp keeps a
+ * misbehaving or hand-stubbed source from ever exceeding `max`.
+ */
+export function rollInclusive(
+  random: RandomSource,
+  min: number,
+  max: number,
+): number {
+  if (max <= min) {
+    return min;
+  }
+
+  return Math.min(max, min + Math.floor(random.next() * (max - min + 1)));
+}