Pikurn: A Betting Game with a Twist

1
/** Pikurn: finite, adaptive betting without replacement. No runtime dependencies. */
2
export type State = Readonly<{ g: number; r: number; b: number; n: number }>
3
export type Objective = 'expected' | 'guaranteed'
4
export type Outcome = 'G' | 'R' | 'B'
5
export type Decision = Readonly<{ value: number; fraction: number }>
6
export type Policy = (state: State) => number
7
export type Branch = Readonly<{ outcome: Outcome; probability: number; next: State | null }>
8
export type TerminalPath = Readonly<{ path: Outcome[]; probability: number; wealth: number }>
9

10
/** Extra requested draws are harmless: the game also ends when the bag empties. */
11
function normalize(state: State): State {
12
  for (const key of ['g', 'r', 'b', 'n'] as const) {
13
    if (!Number.isSafeInteger(state[key]) || state[key] < 0) {
14
      throw new RangeError(`${key} must be a nonnegative safe integer`)
15
    }
16
  }
17
  const total = state.g + state.r + state.b
18
  if (!Number.isSafeInteger(total)) throw new RangeError('The bag total must be a safe integer')
19
  return { ...state, n: Math.min(state.n, total) }
20
}
21

22
function branches(state: State): Branch[] {
23
  if (state.n === 0) return []
24
  const total = state.g + state.r + state.b
25
  const result: Branch[] = []
26
  if (state.g) {
27
    result.push({
28
      outcome: 'G',
29
      probability: state.g / total,
30
      next: { ...state, g: state.g - 1, n: state.n - 1 },
31
    })
32
  }
33
  if (state.r) {
34
    result.push({
35
      outcome: 'R',
36
      probability: state.r / total,
37
      next: { ...state, r: state.r - 1, n: state.n - 1 },
38
    })
39
  }
40
  if (state.b) result.push({ outcome: 'B', probability: state.b / total, next: null })
41
  return result
42
}
43

44
/** Feasible draws only. Blue returns the stake and immediately terminates play. */
45
export function outcomes(state: State): Branch[] {
46
  return branches(normalize(state))
47
}
48

49
export function transition(state: State, outcome: Outcome): State | null {
50
  const branch = outcomes(state).find((candidate) => candidate.outcome === outcome)
51
  if (!branch) throw new RangeError(`Cannot draw ${outcome} from this state`)
52
  return branch.next
53
}
54

55
type Line = { intercept: number; slope: number }
56

57
function finite(value: number, quantity: string): number {
58
  if (!Number.isFinite(value)) {
59
    throw new RangeError(`${quantity} exceeded the finite IEEE-754 number range`)
60
  }
61
  return value
62
}
63

64
/** Maximum of a lower envelope of affine functions occurs at an endpoint or crossing. */
65
function guarantee(lines: Line[]): Decision {
66
  const candidates = [0, 1]
67
  for (let i = 0; i < lines.length; i++) {
68
    for (let j = i + 1; j < lines.length; j++) {
69
      const a = lines[i]!
70
      const b = lines[j]!
71
      if (a.slope === b.slope) continue
72
      const difference = finite(b.intercept - a.intercept, 'Continuation difference')
73
      const slope = finite(a.slope - b.slope, 'Continuation slope difference')
74
      const f = finite(difference / slope, 'Candidate wager')
75
      if (f > 0 && f < 1) candidates.push(f)
76
    }
77
  }
78
  let best: Decision | undefined
79
  for (const fraction of candidates.sort((a, b) => a - b)) {
80
    const value = Math.min(
81
      ...lines.map((line) => finite(line.intercept + line.slope * fraction, 'Normalized wealth'))
82
    )
83
    // Floating-point near ties retain the smaller wager; errors scale with the value.
84
    const tolerance = 32 * Number.EPSILON * Math.max(1, value, best?.value ?? 0)
85
    if (!best || value - best.value > tolerance) best = { value, fraction }
86
  }
87
  return best!
88
}
89

90
/**
91
 * Optimal terminal wealth per starting dollar and first wager fraction.
92
 * Later decisions are adaptive: solve again after observing each draw.
93
 * Values use IEEE-754 arithmetic, not rational arithmetic or Monte Carlo.
94
 * Numerical overflow throws RangeError instead of returning a misleading policy.
95
 */
96
export function solve(input: State, objective: Objective = 'expected'): Decision {
97
  if (objective !== 'expected' && objective !== 'guaranteed') {
98
    throw new RangeError('Unknown objective')
99
  }
100
  const initial = normalize(input)
101
  const memo = new Map<string, Decision>()
102
  function visit(state: State): Decision {
103
    if (state.n === 0) return { value: 1, fraction: 0 }
104
    const key = `${state.g},${state.r},${state.b},${state.n}`
105
    const cached = memo.get(key)
106
    if (cached) return cached
107
    const choices = branches(state)
108
    const lines = choices.map(({ outcome, next }) => {
109
      const value = next ? visit(next).value : 1
110
      return { intercept: value, slope: outcome === 'G' ? value : outcome === 'R' ? -value : 0 }
111
    })
112
    let result: Decision
113
    if (objective === 'expected') {
114
      const intercept = finite(
115
        lines.reduce((sum, line, i) => sum + choices[i]!.probability * line.intercept, 0),
116
        'Expected continuation wealth'
117
      )
118
      const slope = finite(
119
        lines.reduce((sum, line, i) => sum + choices[i]!.probability * line.slope, 0),
120
        'Expected continuation slope'
121
      )
122
      const tolerance = 32 * Number.EPSILON * Math.max(1, intercept)
123
      const fraction = slope > tolerance ? 1 : 0
124
      result = { value: finite(intercept + slope * fraction, 'Normalized wealth'), fraction }
125
    } else result = guarantee(lines)
126
    memo.set(key, result)
127
    return result
128
  }
129
  return visit(initial)
130
}
131

132
/**
133
 * Enumerate every possible color sequence, retaining its true probability.
134
 * This is exponential in the horizon; use small bags for trees and histograms.
135
 * A policy is a deterministic wager fraction based on the observed remaining bag.
136
 * A path whose wealth overflows the finite number range throws RangeError.
137
 */
138
export function enumerate(input: State, policy: Policy, bankroll = 100): TerminalPath[] {
139
  const initial = normalize(input)
140
  if (!Number.isFinite(bankroll) || bankroll < 0)
141
    throw new RangeError('Bankroll must be finite and nonnegative')
142
  const result: TerminalPath[] = []
143
  function walk(state: State | null, path: Outcome[], probability: number, wealth: number): void {
144
    if (!state || state.n === 0) {
145
      result.push({ path, probability, wealth })
146
      return
147
    }
148
    const fraction = policy(state)
149
    if (!Number.isFinite(fraction) || fraction < 0 || fraction > 1) {
150
      throw new RangeError('Policy must return a finite wager fraction in [0, 1]')
151
    }
152
    for (const branch of branches(state)) {
153
      const multiplier =
154
        branch.outcome === 'G' ? 1 + fraction : branch.outcome === 'R' ? 1 - fraction : 1
155
      walk(
156
        branch.next,
157
        [...path, branch.outcome],
158
        probability * branch.probability,
159
        finite(wealth * multiplier, 'Path wealth')
160
      )
161
    }
162
  }
163
  walk(initial, [], 1, bankroll)
164
  return result
165
}
166

167
// Node 24.2+ runs TypeScript directly. Importing this module never runs the CLI.
168
// Usage: node pikurn.ts [green=2] [red=1] [blue=0] [draws=bag-size] [bankroll=100]
169
if (import.meta.main) {
170
  const args = process.argv.slice(2).map(Number)
171
  const g = args[0] ?? 2
172
  const r = args[1] ?? 1
173
  const b = args[2] ?? 0
174
  const state: State = { g, r, b, n: args[3] ?? g + r + b }
175
  const bankroll = args[4] ?? 100
176
  for (const objective of ['expected', 'guaranteed'] as const) {
177
    const decision = solve(state, objective)
178
    console.log(
179
      `${objective}: first wager ${(100 * decision.fraction).toFixed(2)}%; value $${(bankroll * decision.value).toFixed(2)}`
180
    )
181
    console.table(
182
      enumerate(state, (next) => solve(next, objective).fraction, bankroll).map((leaf) => ({
183
        path: leaf.path.join('') || '(no draws)',
184
        probability: leaf.probability,
185
        wealth: leaf.wealth,
186
      }))
187
    )
188
  }
189
}