The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import { describe, expect, it } from 'vitest'
import {
applyZooOps, draw, drawWeights, emptyZoo, ZOO_FIRST_NEW, ZOO_NEW_AFTER, type Rng, type Zoo, type ZooDaemon, type ZooEgg, type ZooOp,
} from './zoo.js'
import { DAEMON_ROSTER } from './daemonRoster.g.js'
/**
* The draw, measured. Every test here runs the real draw (and, where it matters, the real hatch op) with a
* seeded generator hundreds of thousands of times and holds the observed frequencies to what the roster
* says (daemons/README.md, "The draw") — computed here from the README's rules, not from `drawWeights`.
*
* Tolerances: a chi-square goodness-of-fit at alpha = 0.001 over every daemon that can come out, and each
* proportion within 4.5 standard errors. The seeds are fixed, so a run is reproducible; the bounds are wide
* enough that a correct draw passes for essentially any seed and tight enough that a mis-weighted one
* (a lost boost, a secret leaking into an egg that cannot hold one) fails by orders of magnitude (see
* "the tests have power").
*/
const R = DAEMON_ROSTER.rules
/** After drop 1's (init) release on 2026-09-27, with unix and tty on hold: drop 1 is every daemon a draw can give. */
const NOW = new Date('2026-10-01T12:00:00.000Z')
const OUT = new Set(DAEMON_ROSTER.drops.filter((d) => 'release' in d && Date.parse(`${d.release}T00:00:00.000Z`) <= NOW.getTime()).map((d) => d.id))
const ROSTER = DAEMON_ROSTER.daemons.filter((d) => OUT.has(d.drop))
const KINDS = Object.keys(R.eggs) as Array<keyof typeof R.eggs>
const REGULARS: readonly string[] = ROSTER.filter((d) => d.rarity !== 'secret').map((d) => d.id)
const SECRETS: readonly string[] = ROSTER.filter((d) => d.rarity === 'secret').map((d) => d.id)
const RARITY = new Map<string, string>(ROSTER.map((d) => [d.id, d.rarity]))
/** An hour on: when a retried request arrives. */
const LATER = new Date('2026-10-01T13:00:00.000Z')
const N = 200_000
const SHINY = 1 / R.shinyOneIn
/** sfc32: a small, well-mixed 128-bit-state generator; two outputs make one 53-bit uniform. */
function seeded(seed: number): Rng {
let a = 0x9e3779b9, b = 0x243f6a88, c = 0xb7e15162, d = seed >>> 0
const u32 = (): number => {
const t = (((a + b) | 0) + d) | 0
d = (d + 1) | 0
a = b ^ (b >>> 9)
b = (c + (c << 3)) | 0
c = (c << 21) | (c >>> 11)
c = (c + t) | 0
return t >>> 0
}
for (let i = 0; i < 16; i++) u32()
return (n) => Math.floor((((u32() >>> 5) * 67108864 + (u32() >>> 6)) / 9007199254740992) * n)
}
/** The README's numbers for new species ("The draw"): the first 4 hatches, and the one after 8 without. */
const FIRST_NEW = 4
const NEW_AFTER = 8
let uids = 0
const daemon = (id: string): ZooDaemon => ({
uid: (++uids).toString(16).padStart(24, '0'), id, seed: 0, shiny: false, xp: 0, bond: 0, version: '0.1',
hatched: '2026-09-27T00:00:00.000Z', egg: 'first',
})
/** A zoo owning `ids`, one individual each; `hatches` pads it with more of the first (a species hatched
* again), since a zoo's individuals are its hatches. */
const zooOwning = (ids: readonly string[], patch: Partial<Zoo> = {}, hatches = ids.length): Zoo =>
({ ...emptyZoo(), daemons: [...ids, ...Array(hatches - ids.length).fill(ids[0])].map(daemon), ...patch })
const egg = (id: string, kind: string): ZooEgg => ({ id, kind, grantedAt: '2026-09-27T00:00:00.000Z' })
/** What a zoo holds that the draw reads: the species owned, how many hatches, the run since a new one, pity. */
interface State { hatches?: number; sinceNew?: number; pity?: number }
/**
* The README's odds for one hatch, restated independently of the implementation:
* eligible = every regular, owned or not, + unowned secrets when the egg's secret weight is above 0;
* weight = weights[rarity] / (eligible of that rarity), + pity for a secret, x boost. At pity
* secretGuaranteeAt - 1 with an unowned secret, only the unowned secrets. Else, owed a new species (one of
* the first 4 hatches while any is eligible, or after 8 in a row without one while an unowned regular is
* left), only the unowned — unless they weigh nothing for this egg, when it draws as usual. An egg whose
* eligible all weigh nothing draws from everyone.
*/
function expectedOdds(kind: keyof typeof R.eggs, owned: ReadonlySet<string>, state: State = {}): Map<string, number> {
const { hatches = owned.size, sinceNew = 0, pity = 0 } = state
const rule = R.eggs[kind] as { weights: Record<string, number>; boost?: Record<string, number> }
const holdsSecret = (rule.weights.secret ?? 0) > 0
const fresh = REGULARS.filter((id) => !owned.has(id))
const secrets = holdsSecret ? SECRETS.filter((id) => !owned.has(id)) : []
const weigh = (pool: readonly string[]): Map<string, number> => {
const count = new Map<string, number>()
for (const id of pool) count.set(RARITY.get(id)!, (count.get(RARITY.get(id)!) ?? 0) + 1)
return new Map(pool.map((id) => {
const rarity = RARITY.get(id)!
const pityBonus = rarity === 'secret' && holdsSecret ? pity * R.pityPerMiss : 0
return [id, ((rule.weights[rarity] ?? 0) / count.get(rarity)! + pityBonus) * (rule.boost?.[id] ?? 1)]
}))
}
const weighs = (w: Map<string, number>) => [...w.values()].some((x) => x > 0)
let weights: Map<string, number> | null = null
if (secrets.length && pity >= R.secretGuaranteeAt - 1) weights = weigh(secrets)
else {
const owed = (hatches < FIRST_NEW && fresh.length + secrets.length > 0) || (sinceNew >= NEW_AFTER && fresh.length > 0)
if (owed && weighs(weigh([...fresh, ...secrets]))) weights = weigh([...fresh, ...secrets])
weights ??= weigh([...REGULARS, ...secrets])
if (!weighs(weights)) weights = weigh(ROSTER.map((d) => d.id))
}
const total = [...weights.values()].reduce((s, w) => s + w, 0)
return new Map([...weights].map(([id, w]) => [id, w / total]))
}
/** Upper 0.1% points of chi-square, by degrees of freedom. */
const CHI2_999 = [NaN, 10.828, 13.816, 16.266, 18.467, 20.515, 22.458, 24.322, 26.124, 27.877, 29.588, 31.264]
/** Pearson's chi-square of `counts` against `odds`; anything seen that the odds say is impossible is Infinity. */
function chiSquare(counts: ReadonlyMap<string, number>, odds: ReadonlyMap<string, number>, n: number): { chi2: number; df: number } {
let chi2 = 0
let cells = 0
for (const [id, seen] of counts) if (!((odds.get(id) ?? 0) > 0) && seen > 0) return { chi2: Infinity, df: 1 }
for (const [id, p] of odds) {
if (p <= 0) continue
const e = p * n
const o = counts.get(id) ?? 0
chi2 += ((o - e) ** 2) / e
cells++
}
return { chi2, df: Math.max(1, cells - 1) }
}
/** |observed - p| within `z` standard errors of a proportion over `n` trials. */
function expectProportion(seen: number, n: number, p: number, what: string, z = 4.5): void {
const sigma = Math.sqrt((p * (1 - p)) / n)
const observed = seen / n
if (p === 0) { expect(seen, `${what}: impossible, yet seen ${seen} times`).toBe(0); return }
expect(Math.abs(observed - p), `${what}: observed ${observed.toFixed(5)}, expected ${p.toFixed(5)} ± ${(z * sigma).toFixed(5)}`)
.toBeLessThanOrEqual(z * sigma)
}
interface Tally { byId: Map<string, number>; byRarity: Map<string, number>; shiny: number; shinyByRarity: Map<string, number>; n: number }
function tallyDraws(zoo: Zoo, kind: string, n: number, seed: number): Tally {
const rng = seeded(seed)
const t: Tally = { byId: new Map(), byRarity: new Map(), shiny: 0, shinyByRarity: new Map(), n }
for (let i = 0; i < n; i++) {
const d = draw(zoo, kind, rng, NOW)!
t.byId.set(d.id, (t.byId.get(d.id) ?? 0) + 1)
t.byRarity.set(d.rarity, (t.byRarity.get(d.rarity) ?? 0) + 1)
if (d.shiny) { t.shiny++; t.shinyByRarity.set(d.rarity, (t.shinyByRarity.get(d.rarity) ?? 0) + 1) }
}
return t
}
function rarityOdds(odds: ReadonlyMap<string, number>): Map<string, number> {
const out = new Map<string, number>()
for (const [id, p] of odds) out.set(RARITY.get(id)!, (out.get(RARITY.get(id)!) ?? 0) + p)
return out
}
function expectMatches(t: Tally, odds: ReadonlyMap<string, number>, what: string): void {
const { chi2, df } = chiSquare(t.byId, odds, t.n)
expect(chi2, `${what}: chi-square ${chi2.toFixed(2)} on ${df} df`).toBeLessThan(CHI2_999[df])
for (const [id, p] of odds) expectProportion(t.byId.get(id) ?? 0, t.n, p, `${what} ${id}`)
for (const [rarity, p] of rarityOdds(odds)) expectProportion(t.byRarity.get(rarity) ?? 0, t.n, p, `${what} ${rarity}`)
for (const id of t.byId.keys()) expect(odds.has(id), `${what}: ${id} came out but is not eligible`).toBe(true)
}
// One 200,000-draw run per egg kind from a fresh zoo, shared by the tests below.
const FRESH = new Map<string, Tally>()
const freshRun = (kind: string): Tally => {
if (!FRESH.has(kind)) FRESH.set(kind, tallyDraws(emptyZoo(), kind, N, 0xC0FFEE ^ kind.length * 7919 ^ kind.charCodeAt(0)))
return FRESH.get(kind)!
}
describe('the draw, measured: 200,000 hatches per egg kind', () => {
it.each(KINDS)('a fresh %s egg lands on each daemon at the configured odds', (kind) => {
const odds = expectedOdds(kind, new Set())
// The configured weights, as the implementation holds them, are the README's to the millionth.
const units = drawWeights(emptyZoo(), kind, NOW)
const total = units.reduce((s, w) => s + w.weight, 0)
for (const w of units) expect(Math.abs(w.weight / total - (odds.get(w.id) ?? 0))).toBeLessThan(1e-6)
expectMatches(freshRun(kind), odds, `${kind} egg`)
}, 60_000)
it('gives the secret only from an egg whose secret weight is above 0 (night, easter)', () => {
const holding = KINDS.filter((k) => (R.eggs[k].weights as Record<string, number>).secret > 0)
expect(holding.sort()).toEqual(['easter', 'night'])
for (const kind of KINDS) {
const secrets = freshRun(kind).byRarity.get('secret') ?? 0
if (holding.includes(kind)) {
const p = rarityOdds(expectedOdds(kind, new Set())).get('secret')!
expect(p).toBeGreaterThan(0)
expectProportion(secrets, N, p, `${kind} secret`)
} else {
expect(secrets, `${kind} egg gave a secret`).toBe(0)
}
}
// The secret never leaks from a non-secret egg at any pity, however high.
for (const kind of KINDS.filter((k) => !holding.includes(k))) {
const t = tallyDraws(zooOwning([], { pity: R.secretGuaranteeAt - 1 }), kind, 20_000, 77)
expect(t.byRarity.get('secret') ?? 0).toBe(0)
}
}, 60_000)
it('makes tim the likely first hatch: his boosted share of the first egg', () => {
const first = R.eggs.first as { weights: Record<string, number>; boost: Record<string, number> }
const commons = ROSTER.filter((d) => d.rarity === 'common').length
const timWeight = (first.weights.common / commons) * first.boost.tim
const total = first.weights.common - first.weights.common / commons + timWeight + first.weights.rare + first.weights.legendary
const share = timWeight / total // 60 / 144 in drop 1
expect(share).toBeCloseTo(60 / 144, 12)
expectProportion(freshRun('first').byId.get('tim') ?? 0, N, share, 'tim from the first egg')
// Nobody else comes close: tim alone outdraws every rare and legendary together.
const t = freshRun('first')
expect(t.byId.get('tim')!).toBeGreaterThan((t.byRarity.get('rare') ?? 0) + (t.byRarity.get('legendary') ?? 0))
}, 60_000)
it('makes tim the likely first hatch through the real flow: three habits, the first egg, its hatch', () => {
const rng = seeded(4242)
let tim = 0
let shiny = 0
const n = N
for (let i = 0; i < n; i++) {
const granted = applyZooOps(emptyZoo(), [
{ op: 'zoo.habit', key: 'turn' }, { op: 'zoo.habit', key: 'split' }, { op: 'zoo.habit', key: 'find' },
], rng, NOW)
expect(granted.grants.length).toBe(1)
const hatched = applyZooOps(granted.zoo, [{ op: 'zoo.hatch', eggId: granted.grants[0].eggId! }], rng, NOW)
const h = hatched.hatched[0]
if (h.daemonId === 'tim') tim++
if (h.shiny) shiny++
expect(hatched.zoo.paired).toBe(h.uid)
}
expectProportion(tim, n, expectedOdds('first', new Set()).get('tim')!, 'tim through the flow')
expectProportion(shiny, n, SHINY, 'shiny through the flow')
}, 120_000)
it('rolls shiny 1 in 256, for every egg kind and independent of who hatched', () => {
let shiny = 0
let total = 0
for (const kind of KINDS) {
const t = freshRun(kind)
expectProportion(t.shiny, t.n, SHINY, `${kind} shiny`)
// Independence: within each rarity that came out often enough to measure, shiny stays 1 in 256.
for (const [rarity, count] of t.byRarity) {
if (count < 20_000) continue
expectProportion(t.shinyByRarity.get(rarity) ?? 0, count, SHINY, `${kind} ${rarity} shiny`)
}
shiny += t.shiny
total += t.n
}
expect(total).toBe(KINDS.length * N)
expectProportion(shiny, total, SHINY, 'shiny over every egg')
}, 60_000)
it('weighs a rarity by how many of it are left while a new species is owed, and gives an emptied rarity to nobody', () => {
expect([ZOO_FIRST_NEW, ZOO_NEW_AFTER]).toEqual([FIRST_NEW, NEW_AFTER])
// [kind, owned, state]: every case owes a new species (under four hatches, or eight without one).
const cases: Array<[keyof typeof R.eggs, string[], State]> = [
['first', ['tim', 'gnu', 'lynx', 'mutt'], { sinceNew: 8 }], // no common left: its 60 goes nowhere
['first', ['tim'], {}], // tim owned: the boost has nothing to boost
['turn', ['tim', 'gnu', 'yak'], {}],
['week', ['yak', 'gopher', 'bug', 'tux', 'auk'], { sinceNew: 8 }], // only commons left
['marathon', ['tim', 'gnu', 'lynx', 'mutt', 'tux'], { sinceNew: 11 }],
['night', ['bug'], { pity: 3 }], // the boosted one owned; pity 3 on beastie
['night', [], { pity: 6 }],
['easter', ['tux'], { pity: 2 }],
['turn', ['tim'], { hatches: 3 }], // three tims: still owed a new one
]
for (const [kind, owned, state] of cases) {
const zoo = zooOwning(owned, { pity: state.pity ?? 0, sinceNew: state.sinceNew ?? 0 }, state.hatches)
const odds = expectedOdds(kind, new Set(owned), state)
for (const id of owned) expect(odds.has(id), `${kind} would give ${id} again`).toBe(false)
expectMatches(tallyDraws(zoo, kind, N, 900 + (state.pity ?? 0) + owned.length), odds, `${kind} owning [${owned}] ${JSON.stringify(state)}`)
}
}, 120_000)
it('draws every regular at its rarity\'s share once no new species is owed, owned or not', () => {
const cases: Array<[keyof typeof R.eggs, string[], State]> = [
['turn', ['tim', 'gnu', 'yak', 'tux'], {}], // the fifth hatch: owned ones come again
['first', ['gnu', 'lynx', 'mutt', 'yak', 'bug'], { sinceNew: 7 }], // one short of the guarantee
['week', REGULARS.slice(0, 8), { sinceNew: 3 }],
['night', ['tim', 'gnu', 'lynx', 'mutt'], { pity: 4, sinceNew: 5 }],
['turn', [...REGULARS], { sinceNew: 40 }], // every regular owned: nothing to owe
['night', [...REGULARS], { sinceNew: 40, pity: 2 }],
]
for (const [kind, owned, state] of cases) {
const zoo = zooOwning(owned, { pity: state.pity ?? 0, sinceNew: state.sinceNew ?? 0 })
const odds = expectedOdds(kind, new Set(owned), state)
for (const id of REGULARS) expect(odds.get(id), `${kind}: ${id} not eligible`).toBeGreaterThan(0)
expectMatches(tallyDraws(zoo, kind, N, 1900 + (state.sinceNew ?? 0) + owned.length), odds, `${kind} owning [${owned}] ${JSON.stringify(state)}`)
}
}, 120_000)
it('the tests have power: a lost boost or a leaked secret fails by orders of magnitude', () => {
const t = freshRun('first')
const noBoost = new Map([...expectedOdds('setup', new Set())]) // setup: the first egg's weights, no boost
const lost = chiSquare(t.byId, noBoost, t.n)
expect(lost.chi2).toBeGreaterThan(100 * CHI2_999[lost.df])
// A turn egg that could hold beastie (as if its secret weight were the night egg's) would be told apart too.
const leaky = new Map([...expectedOdds('turn', new Set())].map(([id, p]) => [id, p * 0.92] as [string, number]))
leaky.set('beastie', 0.08)
expect(chiSquare(freshRun('turn').byId, leaky, N).chi2).toBeGreaterThan(100 * CHI2_999[9])
}, 60_000)
})
// ── The pity guarantee ───────────────────────────────────────────────────────────────────────────
/**
* The exact distribution of which night hatch (1..8) first gives beastie, from a fresh zoo hatching only
* night eggs: the chance of every (regulars owned, hatches since a new one) carried forward a hatch at a
* time, each with the README's odds (pity is the hatch count, as every egg is a night egg).
*/
function beastieArrival(): number[] {
const arrival = new Array(R.secretGuaranteeAt + 1).fill(0)
let states = new Map<string, number>([['|0', 1]]) // 'owned,ids|sinceNew' -> chance
for (let hatch = 1; hatch <= R.secretGuaranteeAt; hatch++) {
const next = new Map<string, number>()
for (const [key, p] of states) {
const [list, since] = key.split('|')
const owned = new Set(list ? list.split(',') : [])
const odds = expectedOdds('night', owned, { hatches: hatch - 1, sinceNew: Number(since), pity: hatch - 1 })
for (const [id, q] of odds) {
if (q <= 0) continue
if (RARITY.get(id) === 'secret') { arrival[hatch] += p * q; continue }
const now = [...new Set([...owned, id])].sort().join(',')
const k = `${now}|${owned.has(id) ? Number(since) + 1 : 0}`
next.set(k, (next.get(k) ?? 0) + p * q)
}
}
states = next
}
return arrival
}
describe('the dark egg: the secret by the 8th egg that can hold it', () => {
const players = N
it(`always gives beastie by the ${R.secretGuaranteeAt}th night egg, at the README's odds for each hatch (${players} players)`, () => {
const rng = seeded(8)
const seen = new Array(R.secretGuaranteeAt + 1).fill(0)
const eggs = Array.from({ length: R.secretGuaranteeAt }, (_, i) => egg(`n${i + 1}`, 'night'))
const ops: ZooOp[] = eggs.map((e) => ({ op: 'zoo.hatch', eggId: e.id }))
for (let i = 0; i < players; i++) {
const r = applyZooOps({ ...emptyZoo(), eggs }, ops, rng, NOW)
expect(r.hatched.length).toBe(R.secretGuaranteeAt)
// The first four are four species; after that one may come again.
expect(new Set(r.hatched.slice(0, FIRST_NEW).map((h) => h.daemonId)).size).toBe(FIRST_NEW)
expect(r.zoo.daemons.length).toBe(R.secretGuaranteeAt)
const at = r.hatched.findIndex((h) => SECRETS.includes(h.daemonId))
expect(at, 'no beastie in eight night eggs').toBeGreaterThanOrEqual(0)
seen[at + 1]++
// Pity counts the night hatches since beastie.
expect(r.zoo.pity).toBe(R.secretGuaranteeAt - 1 - at)
}
const exact = beastieArrival()
expect(exact.reduce((s, p) => s + p, 0)).toBeCloseTo(1, 12)
expect(exact[1]).toBeCloseTo(8 / 130, 12) // drop 1: 8 of 130 on the first night egg
// The guarantee carries the most weight: the 8th hatch is the likeliest single arrival.
for (let k = 1; k < R.secretGuaranteeAt; k++) expect(exact[R.secretGuaranteeAt]).toBeGreaterThan(exact[k])
const odds = new Map(exact.map((p, k) => [String(k), p] as [string, number]).filter(([, p]) => p > 0))
const counts = new Map(seen.map((c, k) => [String(k), c] as [string, number]).filter(([, c]) => c > 0))
const { chi2, df } = chiSquare(counts, odds, players)
expect(chi2, `arrival chi-square ${chi2.toFixed(2)} on ${df} df`).toBeLessThan(CHI2_999[df])
for (const [k, p] of odds) expectProportion(counts.get(k) ?? 0, players, p, `beastie at night hatch ${k}`)
}, 120_000)
it('holds across night and easter eggs mixed with eggs that cannot hold it, which never move the pity', () => {
const rng = seeded(88)
const pickKind = (): string => KINDS[rng(KINDS.length)]
for (let player = 0; player < 20_000; player++) {
let zoo = emptyZoo()
let capable = 0
for (let step = 0; step < 40 && !zoo.daemons.some((d) => SECRETS.includes(d.id)); step++) {
const kind = pickKind()
const pityBefore = zoo.pity
const r = applyZooOps({ ...zoo, eggs: [egg('x', kind)] }, [{ op: 'zoo.hatch', eggId: 'x' }], rng, NOW)
zoo = r.zoo
const holds = kind === 'night' || kind === 'easter'
if (holds) capable++
if (!holds) expect(zoo.pity, `${kind} moved the pity`).toBe(pityBefore)
expect(capable, 'the 8th egg that could hold beastie did not').toBeLessThanOrEqual(R.secretGuaranteeAt)
}
if (capable === R.secretGuaranteeAt) expect(zoo.daemons.some((d) => SECRETS.includes(d.id))).toBe(true)
}
}, 120_000)
it('guarantees from any stored pity: at 7 the next egg that can hold it is beastie, every time', () => {
const rng = seeded(7)
for (const kind of ['night', 'easter']) {
const t = tallyDraws(zooOwning(['tim', 'yak'], { pity: R.secretGuaranteeAt - 1 }), kind, 20_000, 7)
expect(t.byId.get('beastie')).toBe(20_000)
const r = applyZooOps(zooOwning([], { pity: 999, eggs: [egg('e', kind)] }), [{ op: 'zoo.hatch', eggId: 'e' }], rng, NOW)
expect(r.hatched[0].daemonId).toBe('beastie')
expect(r.zoo.pity).toBe(0)
}
// With beastie owned, pity guarantees nothing: a night egg draws its regulars at its usual odds.
const owned = zooOwning(['beastie'], { pity: R.secretGuaranteeAt - 1 })
expectMatches(tallyDraws(owned, 'night', N, 70), expectedOdds('night', new Set(['beastie']), { pity: R.secretGuaranteeAt - 1 }), 'night with beastie owned')
const later = zooOwning(['beastie', 'tim', 'gnu', 'yak'], { pity: R.secretGuaranteeAt - 1 })
expectMatches(tallyDraws(later, 'night', N, 71), expectedOdds('night', new Set(['beastie', 'tim', 'gnu', 'yak']), { pity: R.secretGuaranteeAt - 1 }), 'night with beastie owned, four hatches in')
}, 120_000)
})
// ── New species: the first four, and never nine in a row without one ────────────────────────────
describe('new species: the first four hatches, and one after eight without', () => {
/** Egg kinds for these runs: easter one time in three, so its exception (below) is exercised often. */
const pickKind = (rng: Rng): string => (rng(3) === 0 ? 'easter' : KINDS[rng(KINDS.length)])
/** Whether an easter egg has no species to give that the zoo lacks: tux, auk and beastie all owned. */
const easterHasNothingNew = (owned: ReadonlySet<string>) => ['tux', 'auk', 'beastie'].every((id) => owned.has(id))
it('hatches four different species first, whatever the eggs (20,000 accounts)', () => {
const rng = seeded(99)
let easterExceptions = 0
for (let account = 0; account < 20_000; account++) {
let zoo = emptyZoo()
for (let i = 0; i < FIRST_NEW; i++) {
const kind = pickKind(rng)
const owned = new Set(zoo.daemons.map((d) => d.id))
const r = applyZooOps({ ...zoo, eggs: [egg('x', kind)] }, [{ op: 'zoo.hatch', eggId: 'x' }], rng, NOW)
const got = r.hatched[0].daemonId
if (owned.has(got)) {
// The one exception (README, "The draw"): an easter egg, which gives only legendaries and the secret,
// after those three were the first three hatches. It gives a legendary again rather than nobody.
expect(kind).toBe('easter')
expect(easterHasNothingNew(owned)).toBe(true)
easterExceptions++
}
zoo = r.zoo
}
expect(zoo.daemons.length).toBe(FIRST_NEW)
}
expect(easterExceptions).toBeGreaterThan(0) // the exception is exercised, not assumed
}, 120_000)
it('never hatches nine in a row without a new species while an unowned regular is left (5,000 collections)', () => {
const rng = seeded(1999)
let guaranteed = 0
let easterWaits = 0
let longest = 0
for (let c = 0; c < 5_000; c++) {
let zoo = emptyZoo()
let dry = 0
for (let step = 0; step < 400 && !REGULARS.every((id) => zoo.daemons.some((d) => d.id === id)); step++) {
const kind = pickKind(rng)
const owned = new Set(zoo.daemons.map((d) => d.id))
const r = applyZooOps({ ...zoo, eggs: [egg('x', kind)] }, [{ op: 'zoo.hatch', eggId: 'x' }], rng, NOW)
const isNew = !owned.has(r.hatched[0].daemonId)
if (dry >= NEW_AFTER && !isNew) {
// Owed a new one, it gave one owned: only an easter egg with no legendary or secret left to give.
expect(kind).toBe('easter')
expect(easterHasNothingNew(owned)).toBe(true)
easterWaits++
} else if (dry >= NEW_AFTER) {
guaranteed++
}
dry = isNew ? 0 : dry + 1
expect(r.zoo.sinceNew).toBe(dry) // the zoo counts the run as the README does
longest = Math.max(longest, kind === 'easter' ? 0 : dry)
zoo = r.zoo
}
expect(REGULARS.every((id) => zoo.daemons.some((d) => d.id === id))).toBe(true)
// Every hatch an individual of its own.
expect(new Set(zoo.daemons.map((d) => d.uid)).size).toBe(zoo.daemons.length)
}
expect(guaranteed).toBeGreaterThan(100) // the guarantee is exercised, not assumed
expect(easterWaits).toBeGreaterThan(0)
expect(longest).toBeLessThanOrEqual(NEW_AFTER)
}, 180_000)
it('owed a new species after eight without, draws the unowned at their odds', () => {
const cases: Array<[keyof typeof R.eggs, string[]]> = [
['turn', ['tim', 'gnu', 'lynx', 'mutt', 'yak']],
['first', ['gnu', 'lynx', 'mutt', 'yak', 'gopher', 'bug', 'tux', 'auk']], // only tim left: always tim
['night', ['tim', 'gnu', 'lynx', 'mutt', 'yak', 'gopher']], // beastie beside the unowned
['easter', ['tim', 'gnu', 'lynx', 'mutt', 'yak', 'tux']], // only auk and beastie are new
]
for (const [kind, owned] of cases) {
const state: State = { sinceNew: NEW_AFTER }
const zoo = zooOwning(owned, { sinceNew: NEW_AFTER })
const odds = expectedOdds(kind, new Set(owned), state)
for (const id of owned) expect(odds.has(id), `${kind} owed a new one would give ${id}`).toBe(false)
expectMatches(tallyDraws(zoo, kind, N, 3100 + owned.length), odds, `${kind} owed a new one, owning [${owned}]`)
}
}, 120_000)
})
// ── Replay and racing writers ────────────────────────────────────────────────────────────────────
const DAYS = ['2026-09-29', '2026-09-30', '2026-10-01', '2026-10-02']
const WORDS = ['xyzzy', 'plugh', 'XYZZY']
/**
* A random op a client could send against `zoo`: mostly names that exist there, some that do not. With
* `seenOnly`, an individual or a species is named only when the zoo holds it — what a client that saw this
* zoo can name.
*/
function randomOp(zoo: Zoo, rng: Rng, seenOnly = false): ZooOp {
const pick = <T>(xs: readonly T[]): T => xs[rng(xs.length)]
const someDaemon = (): string => (zoo.daemons.length && (seenOnly || rng(4)) ? pick(zoo.daemons).id : seenOnly ? 'nobody' : pick(ROSTER).id)
const someUid = (): string => (zoo.daemons.length && (seenOnly || rng(4)) ? pick(zoo.daemons).uid : rng(0x1_0000_0000).toString(16).padStart(24, 'f'))
switch (rng(10)) {
case 0: return { op: 'zoo.habit', key: pick([...R.firstEgg.habits, 'bogus']) }
case 1: case 2: return { op: 'zoo.hatch', eggId: zoo.eggs.length && rng(5) ? pick(zoo.eggs).id : `gone${rng(3)}` }
case 3: return { op: 'zoo.pair', uid: someUid() }
case 4: return { op: 'zoo.nickname', uid: someUid(), name: rng(3) ? pick(['Tim', 'x', 'grue!']) : null }
case 5: return { op: 'zoo.autonomy', level: pick(['watch', 'suggest', 'act-on-key', 'act-within-rules', 'future']) }
case 6: return { op: 'zoo.easter', word: pick(WORDS) }
// A lesson for a daemon you do not own grows the paired one; with nothing paired yet it waits (it is not
// remembered), so a batch that hatches your first daemon would credit it on the replay. A client that saw
// no pair has nothing to credit, so `seenOnly` sends none.
case 7: return seenOnly && zoo.paired === null ? { op: 'zoo.habit', key: 'days' } : { op: 'zoo.lesson', lessonId: `l${rng(6)}`, daemonId: someDaemon() }
default: {
const n = 1 + rng(30)
return {
op: 'zoo.turn', batchId: `b${rng(40)}`, n, minutes: rng(2) ? rng(300) : undefined, away: rng(2) ? rng(n + 1) : undefined,
day: pick(DAYS), hour: rng(24), machineId: pick(['m1', 'm2', 'm3']),
}
}
}
}
/** A zoo reached by real ops from empty: some daemons, eggs, progress, the dial and consent moved. */
function reachableZoo(rng: Rng, steps: number): Zoo {
let zoo = applyZooOps(emptyZoo(), [
{ op: 'zoo.habit', key: 'turn' }, { op: 'zoo.habit', key: 'split' }, { op: 'zoo.habit', key: 'find' },
], rng, NOW).zoo
for (let i = 0; i < steps; i++) {
const ops = Array.from({ length: 1 + rng(6) }, () => randomOp(zoo, rng))
if (rng(8) === 0) ops.push({ op: 'zoo.consent', watching: rng(2) === 0 })
zoo = applyZooOps(zoo, ops, rng, NOW).zoo
}
return zoo
}
describe('replay: the same request twice changes nothing the second time', () => {
it('every single op is idempotent from any reachable zoo (5,000 zoos x 8 ops)', () => {
const rng = seeded(2026)
for (let z = 0; z < 5_000; z++) {
const zoo = reachableZoo(rng, rng(12))
for (let k = 0; k < 8; k++) {
const op = k === 7 ? { op: 'zoo.consent' as const, watching: rng(2) === 0 } : randomOp(zoo, rng)
const once = applyZooOps(zoo, [op], rng, NOW)
const twice = applyZooOps(once.zoo, [op], rng, NOW)
expect(twice.changed, JSON.stringify(op)).toBe(false)
expect(twice.zoo).toEqual(once.zoo)
expect(twice.hatched).toEqual([])
expect(twice.grants).toEqual([])
expect(twice.levelUps).toEqual([])
}
}
}, 120_000)
// A batch is what one client queued against the zoo it last saw, so it names only daemons that zoo held.
// (An op naming a daemon the same batch hatches is dropped on the first delivery and lands on the replay:
// no client can send one, since the draw is the server's.)
it('a replayed batch lands on the state the first delivery left (5,000 batches of up to 64 ops)', () => {
const rng = seeded(64)
for (let z = 0; z < 5_000; z++) {
const zoo = reachableZoo(rng, rng(8))
// Consent answered any number of times, before and after dial moves: no exception (see below).
const ops = Array.from({ length: 1 + rng(64) }, () => (rng(10) ? randomOp(zoo, rng, true) : { op: 'zoo.consent' as const, watching: rng(2) === 0 }))
const once = applyZooOps(zoo, ops, rng, NOW)
// Delivered again an hour later: consent's time is the first delivery's, like everything else.
const twice = applyZooOps(once.zoo, ops, rng, LATER)
expect(twice.zoo, JSON.stringify(ops)).toEqual(once.zoo)
expect(twice.hatched).toEqual([])
expect(twice.grants).toEqual([])
}
}, 120_000)
})
describe('replay: consent and the dial, in any order', () => {
// Found by the replay property above (it held these out as a known exception until fixed): `zoo.consent
// { watching: true }` dropped the dial to `watch` only on the transition, so its effect depended on the
// consent it found, and a retried request (its answer lost) landed somewhere else than the first delivery:
// - [dial up, agree]: the first delivery lands at `watch`; the replay found consent given, kept the dial
// move and ended ABOVE `watch`, at a level the person never chose after agreeing.
// - [agree, revoke] on a zoo agreed at act-on-key: the first delivery kept act-on-key; the replay agreed
// from "revoked", which dropped it to `watch`.
// Now each op is an assignment in the person's order — a level sets the dial, a yes sets it to `watch`
// (every yes, a repeated one too), a no leaves it — and consent's time moves only when a request changes
// the answer. So a request lands in the same place however often it arrives.
const dialUpThenAgree: ZooOp[] = [{ op: 'zoo.autonomy', level: 'act-on-key' }, { op: 'zoo.consent', watching: true }]
const agreeThenRevoke: ZooOp[] = [{ op: 'zoo.consent', watching: true }, { op: 'zoo.consent', watching: false }]
const agreed: Zoo = { ...emptyZoo(), autonomy: 'act-on-key', consent: { watching: true, at: '2026-09-30T00:00:00.000Z' } }
it('a replay of [dial up, agree to be watched] stays at watch', () => {
const once = applyZooOps(emptyZoo(), dialUpThenAgree, seeded(1), NOW)
expect(once.zoo).toMatchObject({ autonomy: 'watch', consent: { watching: true, at: NOW.toISOString() } })
const twice = applyZooOps(once.zoo, dialUpThenAgree, seeded(1), LATER)
expect(twice.zoo).toEqual(once.zoo)
expect(twice.changed).toBe(false)
})
it('a replay of [agree, revoke] keeps the dial where the first delivery left it', () => {
// The yes starts the dial at watch (the person agreed again, so they opt in again); the no keeps it.
const once = applyZooOps(agreed, agreeThenRevoke, seeded(1), NOW)
expect(once.zoo).toMatchObject({ autonomy: 'watch', consent: { watching: false, at: NOW.toISOString() } })
const twice = applyZooOps(once.zoo, agreeThenRevoke, seeded(1), LATER)
expect(twice.zoo).toEqual(once.zoo)
expect(twice.changed).toBe(false)
})
// Everything a person can do to these two in one request, in every order: each of the six moves below,
// every sequence of up to four (so every permutation of every choice of four), from every start there is.
type Move = 'watch' | 'suggest' | 'act-on-key' | 'act-within-rules' | 'agree' | 'revoke'
const MOVES: Move[] = ['watch', 'suggest', 'act-on-key', 'act-within-rules', 'agree', 'revoke']
const opOf = (move: Move): ZooOp => move === 'agree' || move === 'revoke'
? { op: 'zoo.consent', watching: move === 'agree' }
: { op: 'zoo.autonomy', level: move }
const sequences = (n: number): Move[][] => n === 0 ? [[]] : sequences(n - 1).flatMap((s) => MOVES.map((m) => [...s, m]))
const ALL = [1, 2, 3, 4].flatMap(sequences)
const STARTS: Zoo[] = [null, true, false].flatMap((watching) => (['watch', 'suggest', 'act-on-key', 'act-within-rules'] as const).map((autonomy): Zoo => ({
...emptyZoo(), autonomy, consent: watching === null ? null : { watching, at: '2026-09-29T00:00:00.000Z' },
})))
/** What the person's moves, in their order, say: the last answer, and the last move of the dial — a yes
* being a move to `watch`. Computed from the moves alone, not from the zoo's code. */
const meant = (start: Zoo, moves: Move[]): { autonomy: string; watching: boolean | null } => {
const answers = moves.filter((m) => m === 'agree' || m === 'revoke')
const dial = moves.filter((m) => m !== 'revoke').map((m) => (m === 'agree' ? 'watch' : m))
return {
autonomy: dial.length ? dial[dial.length - 1] : start.autonomy,
watching: answers.length ? answers[answers.length - 1] === 'agree' : start.consent?.watching ?? null,
}
}
it(`every order of up to four moves, from every start: lands where the moves say, and a replay moves nothing (${ALL.length} x ${STARTS.length})`, () => {
for (const start of STARTS) {
for (const moves of ALL) {
const ops = moves.map(opOf)
const why = `${JSON.stringify(start.consent)} ${start.autonomy} + [${moves.join(', ')}]`
const once = applyZooOps(start, ops, seeded(1), NOW)
expect({ autonomy: once.zoo.autonomy, watching: once.zoo.consent?.watching ?? null }, why).toEqual(meant(start, moves))
// Consent's time moves exactly when the request changed the answer.
const moved = (once.zoo.consent?.watching ?? null) !== (start.consent?.watching ?? null)
expect(once.zoo.consent?.at ?? null, why).toBe(moved ? NOW.toISOString() : start.consent?.at ?? null)
expect(once.changed, why).toBe(once.zoo.autonomy !== start.autonomy || moved)
// The replay, later, and a third delivery: nothing moves, nothing is written.
const twice = applyZooOps(once.zoo, ops, seeded(1), LATER)
expect(twice.zoo, why).toEqual(once.zoo)
expect(twice.changed, why).toBe(false)
// One request is the same as the moves sent one at a time (a client that never batched).
const oneByOne = ops.reduce((zoo, op) => applyZooOps(zoo, [op], seeded(1), NOW).zoo, start)
expect({ autonomy: oneByOne.autonomy, watching: oneByOne.consent?.watching ?? null }, why).toEqual(meant(start, moves))
// A level above watch is only ever one the person chose after their last yes.
const lastYes = moves.lastIndexOf('agree')
if (lastYes >= 0 && once.zoo.autonomy !== 'watch') {
expect(moves.slice(lastYes + 1), why).toContain(once.zoo.autonomy)
}
}
}
})
it('a revoked level is never raised again by the yes that follows, in one request or two', () => {
const revoked = applyZooOps(agreed, [{ op: 'zoo.consent', watching: false }], seeded(1), NOW).zoo
expect(revoked).toMatchObject({ autonomy: 'act-on-key', consent: { watching: false } })
expect(applyZooOps(revoked, [{ op: 'zoo.consent', watching: true }], seeded(1), LATER).zoo.autonomy).toBe('watch')
const both = applyZooOps(agreed, [{ op: 'zoo.consent', watching: false }, { op: 'zoo.consent', watching: true }], seeded(1), NOW)
// Agreed before and after: consent (and its time) did not change, but the yes still starts at watch.
expect(both.zoo).toMatchObject({ autonomy: 'watch', consent: agreed.consent })
expect(both.changed).toBe(true)
})
it('two writers racing a yes and a dial move: the later write wins, as the person\'s later move', () => {
// The compare-and-set loser replays its request on the winner's zoo (last writer wins by the zoo's
// revision): the result is the two moves in the order they were written, either of which a person
// could have made — a raise after the yes stands, a yes after the raise starts at watch.
const agree: ZooOp[] = [{ op: 'zoo.consent', watching: true }]
const raise: ZooOp[] = [{ op: 'zoo.autonomy', level: 'suggest' }]
const after = (first: ZooOp[], second: ZooOp[]): Zoo => applyZooOps(applyZooOps(emptyZoo(), first, seeded(1), NOW).zoo, second, seeded(1), NOW).zoo
expect(after(agree, raise)).toMatchObject({ autonomy: 'suggest', consent: { watching: true } })
expect(after(raise, agree)).toMatchObject({ autonomy: 'watch', consent: { watching: true } })
// The later write delivered again changes nothing.
expect(applyZooOps(after(agree, raise), raise, seeded(1), LATER).changed).toBe(false)
expect(applyZooOps(after(raise, agree), agree, seeded(1), LATER).changed).toBe(false)
})
})
/**
* Two (or more) writers racing on one zoo document, the way routes/zoo.ts writes it: read the revision,
* apply the ops, compare-and-set; a writer that lost re-reads and applies its ops again. Interleavings are
* chosen by a seeded scheduler.
*/
describe('racing writers under compare-and-set', () => {
interface Doc { revision: number; zoo: Zoo }
interface Writer { ops: ZooOp[]; phase: 'read' | 'write' | 'done'; seen?: Doc; applied?: ReturnType<typeof applyZooOps>; answered?: ReturnType<typeof applyZooOps>; attempts: number }
function race(start: Zoo, batches: ZooOp[][], rng: Rng): { doc: Doc; writers: Writer[]; commits: number } {
const doc: Doc = { revision: 7, zoo: start }
const writers: Writer[] = batches.map((ops) => ({ ops, phase: 'read', attempts: 0 }))
let commits = 0
for (let guard = 0; writers.some((w) => w.phase !== 'done'); guard++) {
if (guard > 1000) throw new Error('the race never settled')
const live = writers.filter((w) => w.phase !== 'done')
const w = live[rng(live.length)]
if (w.phase === 'read') {
w.attempts++
w.seen = { revision: doc.revision, zoo: doc.zoo }
w.applied = applyZooOps(w.seen.zoo, w.ops, rng, NOW)
if (!w.applied.changed) { w.answered = w.applied; w.phase = 'done'; continue }
w.phase = 'write'
} else if (w.phase === 'write') {
if (doc.revision === w.seen!.revision) {
doc.revision++
doc.zoo = w.applied!.zoo
commits++
w.answered = w.applied
w.phase = 'done'
} else {
w.phase = 'read' // lost the race: replay on the fresh zoo
}
}
}
return { doc, writers, commits }
}
it('two phones hatching the same eggs: each egg hatches once, and each answer is what was written', () => {
const rng = seeded(5150)
for (let trial = 0; trial < 5_000; trial++) {
const eggs = Array.from({ length: 1 + rng(12) }, (_, i) => egg(`e${i}`, KINDS[rng(KINDS.length)]))
const start: Zoo = { ...zooOwning(REGULARS.slice(0, rng(4))), eggs }
const hatchAll = eggs.map((e): ZooOp => ({ op: 'zoo.hatch', eggId: e.id }))
const shuffled = [...hatchAll].sort(() => rng(3) - 1)
const { doc, writers, commits } = race(start, [hatchAll, shuffled], rng)
// The document moved once per write that won; nothing was written twice.
expect(doc.revision).toBe(7 + commits)
expect(doc.zoo.eggs).toEqual([])
const answered = writers.flatMap((w) => w.answered!.hatched)
expect(new Set(answered.map((h) => h.eggId)).size).toBe(answered.length)
expect(answered.map((h) => h.eggId).sort()).toEqual(eggs.map((e) => e.id).sort())
// What the zoo holds is exactly the owned-before plus the individuals answered, each once, as answered.
expect(doc.zoo.daemons.slice(0, start.daemons.length)).toEqual(start.daemons)
const added = doc.zoo.daemons.slice(start.daemons.length)
expect(added.map((d) => d.uid).sort()).toEqual(answered.map((h) => h.uid).sort())
for (const h of answered) {
const { eggId: _egg, daemonId, ...individual } = h
expect(individual.id).toBe(daemonId)
expect(added.find((d) => d.uid === h.uid)).toEqual(individual)
}
expect(new Set(doc.zoo.daemons.map((d) => d.uid)).size).toBe(doc.zoo.daemons.length)
}
}, 120_000)
it('racing turn reports count each batch once, and a batch both machines sent counts once', () => {
const rng = seeded(1984)
for (let trial = 0; trial < 5_000; trial++) {
const day = DAYS[rng(DAYS.length)]
const mk = (id: string, n: number, machineId: string): ZooOp => ({ op: 'zoo.turn', batchId: id, n, day, hour: 10, machineId })
const shared = mk('shared', 1 + rng(5), 'm1')
const a = [shared, mk('a1', 1 + rng(5), 'm1')]
const b = [mk('b1', 1 + rng(5), 'm2'), shared]
const c = [mk('c1', 1 + rng(5), 'm3')]
const { doc } = race(emptyZoo(), [a, b, c], rng)
const n = (op: ZooOp) => (op.op === 'zoo.turn' ? op.n : 0)
const want = Math.min(R.earn.turn.dailyCap, n(shared) + n(a[1]) + n(b[0]) + n(c[0]))
expect(doc.zoo.progress.turns).toBe(want)
expect(doc.zoo.progress.days[day]).toBe(want)
// Four batches of at most 5 never pass the daily cap of 20, so each one counted and is remembered once.
expect([...doc.zoo.progress.batches].sort()).toEqual(['a1', 'b1', 'c1', 'shared'])
// Two machines seen (only the first `earn.marathon.machines` are remembered): the marathon egg, once.
expect(doc.zoo.progress.machines.length).toBe(R.earn.marathon.machines)
expect(doc.zoo.progress.marathon).toEqual(['machines'])
expect(doc.zoo.eggs.filter((e) => e.kind === 'marathon').length).toBe(1)
}
}, 120_000)
it('a first egg claimed by two racing habit reports is granted once', () => {
const rng = seeded(3)
for (let trial = 0; trial < 5_000; trial++) {
const start = { ...emptyZoo(), habits: ['turn', 'split'] }
const { doc, writers } = race(start, [[{ op: 'zoo.habit', key: 'find' }], [{ op: 'zoo.habit', key: 'store' }]], rng)
expect(doc.zoo.eggs.map((e) => e.kind)).toEqual(['first'])
expect(writers.flatMap((w) => w.answered!.grants)).toEqual([{ kind: 'first', eggId: doc.zoo.eggs[0].id }])
expect(doc.zoo.firstEgg).toBe(true)
}
}, 60_000)
})