Deterministic Patterns

How It Works

Uses the djb2 hash algorithm — fast, simple, good distribution:

function djb2Hash(str: string): number {
  let hash = 5381;
  for (let i = 0; i < str.length; i++) {
    hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
  }
  return hash >>> 0; // Ensure unsigned 32-bit
}

// Selection: hash(context) % array.length

API

// Select item from array (throws if array empty)
function deterministicSelect<T>(array: readonly T[], context: string): T;

// Select index from length (throws if length ≤ 0)
function deterministicIndex(length: number, context: string): number;

Context String Design

The context string is the key to good deterministic selection. It should:

1. Uniquely identify the selection context — different situations → different selections
2. Include content-derived data — timestamps, emotions, content types
3. Be stable across runs — don't include process IDs, dates, or random values
4. Be human-readable — for debugging

Good Context Strings

// Includes: purpose + timestamp + content type
`diegetic_${timestamp}_${contentType}`

// Includes: purpose + timestamp + emotion
`reaction_${timestamp}_${emotion}`

// Includes: purpose + two timestamps (for transitions)
`riser_${curr.timestamp}_${prev.timestamp}`

// Includes: purpose + primary emotion
`hook_question_${primaryEmotion}`

Bad Context Strings

// Too generic — same selection for all peaks
`peak`

// Includes runtime state — not reproducible
`sfx_${Date.now()}`

// Includes random value — defeats the purpose
`reaction_${Math.random()}`

Migration Pattern: Math.random() → deterministicSelect()

Before (non-deterministic)

// ❌ WRONG — different result each run
const sfx = library[Math.floor(Math.random() * library.length)];

After (deterministic)

// ✅ CORRECT — same result for same inputs
import { deterministicSelect } from "./deterministicSelect";
const sfx = deterministicSelect(library, `diegetic_${timestamp}_${contentType}`);

Step-by-Step Migration

1. Add import: import { deterministicSelect } from "./deterministicSelect";
2. Identify what data is available at the selection point (timestamps, types, emotions)
3. Construct a context string from available data
4. Replace array[Math.floor(Math.random() * array.length)] with deterministicSelect(array, context)
5. Verify tests still pass
6. Check CI passes (Math.random grep)

Modules Already Migrated

CI Enforcement

The lint job in .github/workflows/ci.yml includes:

- name: Check for Math.random() in server/lib (determinism)
  run: |
    VIOLATIONS=$(grep -rn "Math\.random()" server/lib/ \
      --include="*.ts" \
      | grep -v "vodDownloader/types.ts" \
      | grep -v "deterministicSelect.ts" \
      | grep -v "// " \
      | grep -v "* " \
      || true)
    if [ -n "$VIOLATIONS" ]; then
      echo "::error::Math.random() found in server/lib/. Use deterministicSelect() instead."
      echo "$VIOLATIONS"
      exit 1
    fi

Allowed Exceptions

Test Code

Tests in server/__tests__/ MAY use Math.random() (e.g., randomId(), randomScore()). The CI check only covers server/lib/ production code.

Testing Deterministic Behavior

describe("deterministicSelect", () => {
  it("should always return same result for same context", () => {
    const array = ["a", "b", "c", "d", "e"];
    const result1 = deterministicSelect(array, "test_context");
    const result2 = deterministicSelect(array, "test_context");
    expect(result1).toBe(result2);
  });

  it("should return different results for different contexts", () => {
    const array = ["a", "b", "c", "d", "e"];
    const result1 = deterministicSelect(array, "context_1");
    const result2 = deterministicSelect(array, "context_2");
    // Different contexts should (usually) select different items
    // This is probabilistic but with 5 items, collision is ~20%
  });

  it("should throw for empty array", () => {
    expect(() => deterministicSelect([], "context")).toThrow();
  });
});

Adding New Deterministic Selections

When adding code that needs to select from an array:

1. Never use Math.random() in server/lib/
2. Import deterministicSelect from ./deterministicSelect
3. Design a context string using available data
4. Ensure the context string is unique within the function's scope
5. Add tests verifying deterministic behavior
6. CI will catch any Math.random() violations