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
/**
* The zoo document and the operations that change it — pure, so the rules and the draw can be tested
* without a database (daemons/README.md, "The zoo (server contract)", "First egg: habits" and "Earning
* eggs and growing").
*
* The same ONE RULE as the desk (lib/desk.ts): every op is idempotent and an op on something that is
* not there is dropped, never an error. A client that was offline replays its queue against a zoo that
* moved and every op still means what it meant: a hatch of an egg already hatched lands on nothing, a
* habit already counted counts once, a batch of turns already counted (its `batchId`) counts once.
*
* The draw happens here and only here. Clients never send a result; `rng` is injected so tests are
* deterministic, and is `crypto.randomInt` in production. Eggs earned from work are granted here too:
* a client reports turns, never eggs.
*
* A zoo holds INDIVIDUALS (daemons/README.md, "Individuals"): every hatch is its own, with a server-made
* `uid`, a `seed` its traits follow from (never stored as truth: lib/zooTraits.ts), and a serial. A
* species hatched again is one more individual, never a merge. Ops name an individual by its uid.
*/
import { createHash, randomInt } from 'node:crypto'
import { z } from 'zod'
import { DAEMON_ROSTER } from './daemonRoster.g.js'
export const ZOO_MAX_EGGS = 12
/** Individuals one zoo holds. Full, a hatch is dropped and its egg waits in the nest (earned eggs are
* then held, and past 64 held become xp, as for a full nest). */
export const ZOO_MAX_DAEMONS = 256
export const ZOO_NAME_MAX = 24
/** The highest seed; a hatch draws one from 1 to this. 0 is the species' default traits (an individual
* from before individuals, or a guest's). */
export const ZOO_SEED_MAX = 4_294_967_295
/** An account's first hatches are always a species it does not own (when the egg can give one). */
export const ZOO_FIRST_NEW = 4
/** After this many hatches in a row with no new species, the next is a new one (while an unowned released
* regular exists). */
export const ZOO_NEW_AFTER = 8
/** Far past anything a real account reaches (it resets on every secret); a bound keeps the draw's
* integer weights inside `randomInt`'s range whatever a stored document says. */
export const ZOO_MAX_PITY = 1_000_000
/** Eggs earned while the nest is full wait here, oldest first. 64 turn eggs is months at the daily cap;
* past that each further egg is `rules.overflowXp` for the paired daemon instead. */
export const ZOO_MAX_HELD = 64
/** How many `zoo.turn` batch ids are remembered to drop a replay. A reporter retries within minutes. */
export const ZOO_BATCH_MEMORY = 64
/** How many `zoo.lesson` ids are remembered, so a lesson credits its daemon once. A harnessd retries
* within minutes; 256 is months of lessons at one proposal an hour. */
export const ZOO_LESSON_MEMORY = 256
/** The most turns one `zoo.turn` may report (a reporter batches a minute; the daily cap is far lower). */
export const ZOO_TURN_MAX_N = 50
/** The most agent-minutes one `zoo.turn` may report: a day for each of its turns (harnessd counts at most
* a day for one turn). The daily cap bounds what they earn long before this. */
export const ZOO_TURN_MAX_MINUTES = ZOO_TURN_MAX_N * 24 * 60
/** How many duplicates an old record remembered (read, then dropped: see `parseZoo`). */
const LEGACY_MAX_DUPES = 1_000_000
/** The highest serial a daemon may carry. */
const ZOO_MAX_SERIAL = 1_000_000_000
/** A report may be this many days later than the latest local day on Earth still allows (a retry after
* an offline stretch); anything older, or a day that has not started anywhere yet, is dropped. */
export const ZOO_TURN_LATE_DAYS = 1
const ZOO_MAX_TURNS = 1_000_000_000
const ZOO_MAX_XP = 1_000_000_000
/** Days of per-day counts kept: two ISO weeks, so a week is always whole. */
const DAY_MEMORY = 14
const WEEK_MEMORY = 8
const HISTORY_MEMORY = 16
const DAY_MS = 86_400_000
/** A uniform integer in [0, n). */
export type Rng = (n: number) => number
export const cryptoRng: Rng = (n) => randomInt(n)
// ── What the roster says ─────────────────────────────────────────────────────────────────────────
interface EggRule { weights: Readonly<Record<string, number>>; boost?: Readonly<Record<string, number>> }
interface RosterDaemon { id: string; n: number; drop: string; rarity: string }
/** A drop is announced (shown as silhouettes on shelves) before it is released (drawn from). A drop on
* hold is kept in the roster without dates: never announced, never drawn. */
interface RosterDrop { id: string; announce?: string; release?: string; hold?: boolean }
const RULES = DAEMON_ROSTER.rules
const EGG_RULES: Readonly<Record<string, EggRule>> = RULES.eggs
/** The rule for an egg kind — own keys only, so a kind spelled `constructor` is simply unknown. */
const eggRule = (kind: string): EggRule | undefined => Object.hasOwn(EGG_RULES, kind) ? EGG_RULES[kind] : undefined
/** Only an egg with a secret weight can hold a secret, and only its hatches count toward the pity. */
const holdsSecret = (kind: string): boolean => (eggRule(kind)?.weights.secret ?? 0) > 0
const ROSTER_DAEMONS: readonly RosterDaemon[] = DAEMON_ROSTER.daemons
const DROPS: readonly RosterDrop[] = DAEMON_ROSTER.drops
const ROSTER_IDS: ReadonlySet<string> = new Set(ROSTER_DAEMONS.map((d) => d.id))
const HABIT_KEYS: ReadonlySet<string> = new Set<string>(RULES.firstEgg.habits)
/** Habits the first egg cannot come without (a finished turn). */
const FIRST_REQUIRES: readonly string[] = RULES.firstEgg.require
const EASTER_HASHES: ReadonlySet<string> = new Set<string>(RULES.easterHashes)
const VERSIONS: readonly string[] = RULES.versions
const FIRST_VERSION = VERSIONS[0]
const EARN = RULES.earn
const BOND_LEVELS: readonly number[] = RULES.bond.levels
const BOND_FOR_VERSION: Readonly<Record<string, number>> = RULES.bondForVersion
/** MM-DD → the daemon that date's history egg gives once a drop holds it, or null. */
const HISTORY_DATES: Readonly<Record<string, string | null>> = RULES.historyDates
/** Why a marathon egg was earned; each earns one, once. */
const MARATHON_REASONS = ['turns', 'machines'] as const
/**
* Whether a drop is out at `now`: its `release` day (UTC) has begun. Only released drops hatch; a drop
* that is announced but not yet released is the shelves' silhouettes, never a draw.
*/
export function dropReleased(drop: RosterDrop, now: Date): boolean {
if (drop.hold || !drop.release) return false
return Date.parse(`${drop.release}T00:00:00.000Z`) <= now.getTime()
}
/** Every daemon a draw may give at `now`: the released drops, in roster order. */
export function releasedDaemons(now: Date): RosterDaemon[] {
const out = new Set(DROPS.filter((d) => dropReleased(d, now)).map((d) => d.id))
return ROSTER_DAEMONS.filter((d) => out.has(d.drop))
}
/** The sha256 (hex) of an easter word as `zoo.easter` sends it, trimmed and lowercased. The roster lists
* only these, so the words themselves never ship to a client. */
export function easterHash(word: string): string {
return createHash('sha256').update(word.trim().toLowerCase()).digest('hex')
}
const HASH_RE = /^[0-9a-f]{64}$/
// ── Days, weeks and levels ───────────────────────────────────────────────────────────────────────
const DAY_RE = /^(\d{4})-(\d{2})-(\d{2})$/
/** A local calendar day, `YYYY-MM-DD`, that exists (no 02-30), in years 2000–2999. */
export function isLocalDay(s: string): boolean {
const m = DAY_RE.exec(s)
if (!m) return false
const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])]
if (y < 2000 || y > 2999) return false
const t = new Date(Date.UTC(y, mo - 1, d))
return t.getUTCFullYear() === y && t.getUTCMonth() === mo - 1 && t.getUTCDate() === d
}
/** Days since 1970-01-01 of a calendar day — arithmetic on dates, no time zone involved. */
const dayNumber = (day: string): number => {
const [y, m, d] = day.split('-').map(Number)
return Date.UTC(y, m - 1, d) / DAY_MS
}
const dayOf = (n: number): string => new Date(n * DAY_MS).toISOString().slice(0, 10)
/**
* The night a turn finishing at local `hour` of `day` belongs to, named by the day it began, or null
* outside the night hours. Night hours may run past midnight (22:00 to 06:59): a turn at 02:00 on the
* 22nd belongs to the night of the 21st, like one at 23:00 on the 21st.
*/
export function nightOf(day: string, hour: number): string | null {
const { fromHour, toHour } = EARN.night
if (fromHour <= toHour) return hour >= fromHour && hour <= toHour ? day : null
if (hour >= fromHour) return day
return hour <= toHour ? dayOf(dayNumber(day) - 1) : null
}
/**
* The history dates whose egg is open on `day`: each `MM-DD` of `rules.historyDates`, in the year its
* week began, when `day` falls within `earn.history.days` of it (so 12-30 is open until 01-05). A date is
* named with its year: one egg per date per year.
*/
export function historyDatesOpen(day: string): string[] {
const at = dayNumber(day)
const year = Number(day.slice(0, 4))
const open: string[] = []
for (const mmdd of Object.keys(HISTORY_DATES)) {
for (const y of [year - 1, year]) {
const date = `${y}-${mmdd}`
if (!isLocalDay(date)) continue // 02-29 in a year without one
const since = at - dayNumber(date)
if (since >= 0 && since < EARN.history.days) open.push(date)
}
}
return open.sort()
}
/** The ISO 8601 week a calendar day belongs to, `YYYY-Www` (weeks start on Monday; week 1 holds the
* year's first Thursday, so 2027-01-01 is in 2026-W53 and 2024-12-30 is in 2025-W01). */
export function isoWeek(day: string): string {
const [y, m, d] = day.split('-').map(Number)
const t = new Date(Date.UTC(y, m - 1, d))
t.setUTCDate(t.getUTCDate() + 4 - (t.getUTCDay() || 7)) // the Thursday of that week
const year = t.getUTCFullYear()
const week = Math.floor((t.getTime() - Date.UTC(year, 0, 1)) / DAY_MS / 7) + 1
return `${year}-W${String(week).padStart(2, '0')}`
}
/** Bond level for `xp`: the highest threshold of `rules.bond.levels` reached. */
export function levelFor(xp: number): number {
let level = 0
for (const [i, at] of BOND_LEVELS.entries()) if (xp >= at) level = i
return level
}
/** The version a bond level has grown into (`rules.bondForVersion`). */
export function versionFor(level: number): string {
let version = FIRST_VERSION
for (const v of VERSIONS) if (level >= BOND_FOR_VERSION[v]) version = v
return version
}
// ── Shapes ───────────────────────────────────────────────────────────────────────────────────────
/** A roster id's shape (the same rule daemons/tools/generate.mjs holds the roster to). */
const daemonId = z.string().regex(/^[a-z][a-z0-9-]{0,15}$/)
/** An egg id, a habit key, an egg kind, an easter word, a batch or machine id: short and id-safe. */
const key = z.string().min(1).max(64).regex(/^[A-Za-z0-9_-]+$/)
const isoTime = z.string().max(40).refine((s) => !Number.isNaN(Date.parse(s)), 'not a time')
const localDay = z.string().max(10).refine(isLocalDay, 'not a YYYY-MM-DD day')
/** 1–24 printable ASCII once trimmed: what a status line and a card can draw on every terminal. */
export const zooNameSchema = z.string().trim().regex(/^[\x20-\x7e]{1,24}$/, 'a name must be 1-24 printable ASCII characters')
/** An individual's id: 24 lowercase hex, made by the server (random at a hatch, derived for an old record). */
export const zooUidSchema = z.string().regex(/^[0-9a-f]{24}$/, 'a uid is 24 lowercase hex characters')
const bond = z.number().int().min(0).max(1_000_000)
const version = z.string().refine((v) => VERSIONS.includes(v), 'unknown version')
/** Its mint number: the nth of its species the server hatched (`DaemonMint`). */
const serial = z.number().int().min(1).max(ZOO_MAX_SERIAL)
/** `local`: hatched in a guest's zoo on a client, brought in by `zoo.seed`; it has no serial. */
const origin = z.literal('local')
/** One individual as stored and served. */
export const zooDaemonSchema = z.object({
uid: zooUidSchema,
/** Its species: a roster id. */
id: daemonId,
/** What its traits follow from (lib/zooTraits.ts `rollTraits`). 0: the species' default traits. */
seed: z.number().int().min(0).max(ZOO_SEED_MAX),
/** Absent on a guest's individual and on one hatched before serials. */
serial: serial.optional(),
/** The name the person gave it (at the hatch, or later). */
name: zooNameSchema.optional(),
shiny: z.boolean(),
xp: z.number().int().min(0).max(ZOO_MAX_XP),
bond,
version,
/** When it hatched. */
hatched: isoTime,
/** The kind of egg it came from. */
egg: key,
origin: origin.optional(),
}).strict()
/**
* A daemon as stored before individuals: one record per species, a duplicate merged into it (`dupes`).
* Read as one individual per record (see `parseZoo`); never written again.
*/
const legacyDaemonSchema = z.object({
id: daemonId,
hatchedAt: isoTime,
egg: key,
shiny: z.boolean(),
nickname: zooNameSchema.optional(),
bond,
/** Absent on a daemon stored before xp existed; read as the least xp its bond needs. */
xp: z.number().int().min(0).max(ZOO_MAX_XP).optional(),
version,
dupes: z.number().int().min(1).max(LEGACY_MAX_DUPES).optional(),
serial: serial.optional(),
origin: origin.optional(),
}).strict()
/** `date` is the history date a history egg remembers (`YYYY-MM-DD`, the year its week began); its MM-DD
* picks the daemon it leans toward. */
export const zooEggSchema = z.object({
id: key, kind: key, grantedAt: isoTime, date: localDay.optional(),
/** `local`: an egg a guest's zoo earned on a client, brought in by `zoo.seed` (self-reported). */
origin: z.literal('local').optional(),
}).strict()
export type ZooDaemon = z.infer<typeof zooDaemonSchema>
export type ZooEgg = z.infer<typeof zooEggSchema>
/** An egg earned while the nest was full, waiting for room. */
export interface ZooHeld { kind: string; date?: string }
/**
* What counts toward the eggs earned from work (README, "Earning eggs and growing"). Server-written:
* clients read it to show how close the next egg is and never send it (except a guest's, once, in
* `zoo.seed`).
*/
export interface ZooProgress {
/** Counted turns, all time (after the daily cap): each turn once, plus one per `earn.turn.minutesPerTurn`
* agent-minutes. A turn egg every `earn.turn.every`. */
turns: number
/** Counted turns per local day, the last two weeks. The daily cap and the week egg read this. */
days: Record<string, number>
/** ISO weeks whose week egg was earned, the last few. */
weeks: string[]
/** Nights (named by the local day they began) with a counted turn that finished while the person was
* away, since the last night egg. */
nights: string[]
/** The first machines turns were reported from (up to `earn.marathon.machines`). */
machines: string[]
/** Marathon eggs earned, by reason: `turns`, `machines`. */
marathon: string[]
/** History dates (`YYYY-MM-DD`, the year each week began) whose egg was earned, the last few. */
history: string[]
/** Eggs earned while the nest was full, oldest first. */
held: ZooHeld[]
/** The last `zoo.turn` batch ids applied. */
batches: string[]
/** The last `zoo.lesson` ids credited: a lesson grows its daemon once, however often it is reported. */
lessons: string[]
}
/**
* How much the paired daemon may do on its own (daemons/BRAIN.md, "Autonomy dial"), read by every
* harnessd's pair brain: `watch` (the default) only reads and tells; `suggest` proposes, and every action
* waits for a key; `act-on-key` drives harnesses it started, each other action behind its own key;
* `act-within-rules` also runs the person's `pair.jsonc` rules on the machine that owns a harness. The
* zoo's level is a request: each harnessd acts above `suggest` only after the person confirms it there.
*/
export const ZOO_AUTONOMY_LEVELS = ['watch', 'suggest', 'act-on-key', 'act-within-rules'] as const
export type ZooAutonomy = typeof ZOO_AUTONOMY_LEVELS[number]
export const ZOO_DEFAULT_AUTONOMY: ZooAutonomy = 'watch'
/**
* The person's first-day consent to their daemon watching (daemons/README.md, "What your daemon sees"):
* until `watching` is true no harnessd senses anything. Set only by `zoo.consent`, from a window's consent
* screen; never seeded.
*/
export interface ZooConsent { watching: boolean; at: string }
const isAutonomy = (value: unknown): value is ZooAutonomy =>
typeof value === 'string' && (ZOO_AUTONOMY_LEVELS as readonly string[]).includes(value)
export interface Zoo {
/** Every individual, in the order they hatched. */
daemons: ZooDaemon[]
eggs: ZooEgg[]
/** The uid of the paired individual, or null. */
paired: string | null
/** The autonomy dial. Account state like the pair, so every machine's brain reads the same level. */
autonomy: ZooAutonomy
/** Whether the person agreed to their daemon watching, and when (null: never asked yet). */
consent: ZooConsent | null
habits: string[]
firstEgg: boolean
/** The setup egg (the second habit egg, at `rules.setupEgg.need` habits) has been granted. */
setupEgg: boolean
/** Hatches of eggs that can hold a secret since the last secret. */
pity: number
/** Hatches in a row that gave a species already owned: at `ZOO_NEW_AFTER` the next is a new one. */
sinceNew: number
/** sha256 of each easter word already used. */
easter: string[]
progress: ZooProgress
}
export interface ZooDoc { revision: number; zoo: Zoo }
/**
* What one hatch gave: the new individual as it hatched, with the egg it came from and its species again
* as `daemonId`. `serial` is its mint number, set by the route (routes/zoo.ts).
*/
export type Hatched = ZooDaemon & { eggId: string; daemonId: string }
/** An egg that arrived in the nest during this request (earned now, or held until there was room): its
* `eggId`. Or one earned with 64 already held, which became `xp` for the paired daemon instead. */
export interface Grant { kind: string; eggId?: string; xp?: number }
/** An individual whose bond reached a new level during this request (`id` its species), and the version
* it is now. */
export interface LevelUp { uid: string; id: string; level: number; version: string }
/**
* What a client DRAWS from the zoo, as one comparable string: every individual (its level and version,
* never its xp alone), the eggs, the pair, the dial, consent, the habits and the first and setup eggs. The
* route publishes `zoo_changed` only when this moved (routes/zoo.ts): a `zoo.turn` or `zoo.lesson` that
* only tallied — progress, batch ids, xp short of a level — reaches clients on their next natural read,
* instead of pulling every daemon, window and phone back to `GET /api/zoo` every active minute.
*/
export function shownZoo(zoo: Zoo): string {
return JSON.stringify({
daemons: zoo.daemons.map(({ xp: _xp, ...shown }) => shown),
eggs: zoo.eggs, paired: zoo.paired, autonomy: zoo.autonomy, consent: zoo.consent,
habits: zoo.habits, firstEgg: zoo.firstEgg, setupEgg: zoo.setupEgg,
})
}
/** Whether a client would draw `after` differently from `before` (see `shownZoo`). */
export const zooShownChanged = (before: Zoo, after: Zoo): boolean => shownZoo(before) !== shownZoo(after)
export const emptyProgress = (): ZooProgress =>
({ turns: 0, days: {}, weeks: [], nights: [], machines: [], marathon: [], history: [], held: [], batches: [], lessons: [] })
export const emptyZoo = (): Zoo => ({
daemons: [], eggs: [], paired: null, autonomy: ZOO_DEFAULT_AUTONOMY, consent: null, habits: [], firstEgg: false, setupEgg: false,
pity: 0, sinceNew: 0, easter: [], progress: emptyProgress(),
})
// Names in ops are plain strings rather than roster enums on purpose: a newer client naming a habit or
// a word this server does not know yet gets that op dropped, not the whole batch refused. An individual is
// named by its uid; a well-formed uid the zoo does not hold drops the op like any other missing name.
export const zooOpSchema = z.discriminatedUnion('op', [
z.object({ op: z.literal('zoo.habit'), key }).strict(),
z.object({ op: z.literal('zoo.hatch'), eggId: key }).strict(),
z.object({ op: z.literal('zoo.pair'), uid: zooUidSchema }).strict(),
// The name given at the hatch, or later; null clears it.
z.object({ op: z.literal('zoo.nickname'), uid: zooUidSchema, name: zooNameSchema.nullable() }).strict(),
// A level this server does not know (a newer client's) is dropped, not refused, like any unknown name.
z.object({ op: z.literal('zoo.autonomy'), level: z.string().min(1).max(32) }).strict(),
// The first-day consent screen's answer: whether the daemon may watch at all.
z.object({ op: z.literal('zoo.consent'), watching: z.boolean() }).strict(),
z.object({ op: z.literal('zoo.easter'), word: z.string().min(1).max(64) }).strict(),
// A guest's local zoo, read entry by entry like a stored one (a bad entry is dropped, not the seed).
z.object({ op: z.literal('zoo.seed'), zoo: z.record(z.string(), z.unknown()) }).strict(),
// Turns that finished on one machine, all in one local hour of one local day. harnessd sends it.
// `minutes`: the agent-minutes those turns ran; `away`: how many of them finished while the person was
// away from this computer. Absent means 0 (a harnessd from before either existed).
// SELF-REPORTED, like presence (`away`): anything holding the account's token can send it, so a person can
// only ever cheat their own zoo — the daily cap bounds even that. Nothing here is proof to anyone else:
// a card's serial and rarity are not verified until a later verify endpoint exists.
z.object({
op: z.literal('zoo.turn'),
batchId: key,
n: z.number().int().min(1).max(ZOO_TURN_MAX_N),
minutes: z.number().int().min(0).max(ZOO_TURN_MAX_MINUTES).optional(),
away: z.number().int().min(0).max(ZOO_TURN_MAX_N).optional(),
day: localDay,
hour: z.number().int().min(0).max(23),
machineId: key,
}).strict().refine((op) => (op.away ?? 0) <= op.n, 'away counts turns, so it is at most n'),
// A lesson the person approved (daemons/LEARNING.md): bond for the daemon that found it, named by its
// species (see applyLesson for which individual). harnessd sends it.
// SELF-REPORTED like `zoo.turn`: the approval happened on a machine the server cannot see, so a person can
// only ever grow their own daemons with it (a retry of one lesson id grows nothing).
z.object({ op: z.literal('zoo.lesson'), lessonId: key, daemonId }).strict(),
])
export type ZooOp = z.infer<typeof zooOpSchema>
export const zooOpsBodySchema = z.object({
ops: z.array(zooOpSchema).min(1).max(64),
}).strict()
// ── Reading a stored (or seeded) zoo ─────────────────────────────────────────────────────────────
const record = (raw: unknown): Record<string, unknown> =>
typeof raw === 'object' && raw !== null && !Array.isArray(raw) ? raw as Record<string, unknown> : {}
function uniqueStrings(raw: unknown, keep: (s: string) => boolean, max: number): string[] {
if (!Array.isArray(raw)) return []
const out: string[] = []
for (const item of raw) {
if (typeof item !== 'string' || !key.safeParse(item).success || !keep(item) || out.includes(item)) continue
out.push(item)
if (out.length >= max) break
}
return out
}
/** Like uniqueStrings, but a memory: when there are too many, the newest (last) are the ones kept. */
function lastStrings(raw: unknown, keep: (s: string) => boolean, max: number): string[] {
return uniqueStrings(Array.isArray(raw) ? raw : [], keep, Number.MAX_SAFE_INTEGER).slice(-max)
}
const wholeIn = (raw: unknown, max: number): number =>
typeof raw === 'number' && Number.isInteger(raw) && raw >= 0 ? Math.min(raw, max) : 0
/** Forget per-day counts older than two weeks before the newest day counted. */
function pruneDays(days: Record<string, number>): void {
const keys = Object.keys(days)
if (!keys.length) return
const newest = Math.max(...keys.map(dayNumber))
for (const day of keys) if (dayNumber(day) <= newest - DAY_MEMORY) delete days[day]
}
/** The zoo's progress as stored (or seeded), piece by piece; a malformed piece reads as nothing yet. */
function parseProgress(raw: unknown, strict: boolean): ZooProgress {
const src = record(raw)
const days: Record<string, number> = {}
for (const [day, n] of Object.entries(record(src.days))) {
if (isLocalDay(day) && typeof n === 'number' && Number.isInteger(n) && n > 0) days[day] = Math.min(n, EARN.turn.dailyCap)
}
pruneDays(days)
const held: ZooHeld[] = []
if (Array.isArray(src.held)) {
for (const item of src.held) {
const h = record(item)
if (typeof h.kind !== 'string' || !key.safeParse(h.kind).success) continue
if (strict && !eggRule(h.kind)) continue
held.push(typeof h.date === 'string' && isLocalDay(h.date) ? { kind: h.kind, date: h.date } : { kind: h.kind })
if (held.length >= ZOO_MAX_HELD) break
}
}
return {
turns: wholeIn(src.turns, ZOO_MAX_TURNS),
days,
weeks: lastStrings(src.weeks, (w) => /^\d{4}-W\d{2}$/.test(w), WEEK_MEMORY),
nights: lastStrings(src.nights, isLocalDay, EARN.night.nights - 1),
machines: uniqueStrings(src.machines, () => true, EARN.marathon.machines),
marathon: uniqueStrings(src.marathon, (r) => (MARATHON_REASONS as readonly string[]).includes(r), MARATHON_REASONS.length),
history: lastStrings(src.history, isLocalDay, HISTORY_MEMORY),
held,
batches: lastStrings(src.batches, () => true, ZOO_BATCH_MEMORY),
lessons: lastStrings(src.lessons, () => true, ZOO_LESSON_MEMORY),
}
}
/** An individual's bond and version follow its xp. A daemon stored before xp existed gets the least xp its
* stored bond needs, so reading never lowers a level. */
function grown(d: Omit<ZooDaemon, 'xp'> & { xp?: number }): ZooDaemon {
const xp = d.xp ?? BOND_LEVELS[Math.min(d.bond, BOND_LEVELS.length - 1)]
const bond = levelFor(xp)
return { ...d, xp, bond, version: versionFor(bond) }
}
/**
* The uid an old record reads with: the first 24 hex of sha256 over the account and the species (and,
* for a second record of one species, which one it is), so every read of the same old zoo, before and
* after it is next written, names each individual the same.
*/
export function legacyUid(userId: string, id: string, nth = 0): string {
return createHash('sha256').update(`harness-zoo\0${userId}\0${id}${nth ? `\0${nth}` : ''}`).digest('hex').slice(0, 24)
}
/**
* One stored individual, or an old record read as one (`seed` 0, the species' default traits; its
* `nickname` its name, its `hatchedAt` its hatch, its `dupes` dropped: the xp they gave is in its xp).
* `nth` counts the old records of each species read so far. Null: malformed.
*/
function readDaemon(item: unknown, userId: string, nth: Map<string, number>): ZooDaemon | null {
if (Object.hasOwn(record(item), 'uid')) {
const parsed = zooDaemonSchema.safeParse(item)
return parsed.success ? grown(parsed.data) : null
}
const old = legacyDaemonSchema.safeParse(item)
if (!old.success) return null
const { id, hatchedAt, egg, shiny, nickname, bond, xp, version, serial, origin } = old.data
const k = nth.get(id) ?? 0
nth.set(id, k + 1)
return grown({
uid: legacyUid(userId, id, k), id, seed: 0, ...(serial ? { serial } : {}), ...(nickname ? { name: nickname } : {}),
shiny, xp, bond, version, hatched: hatchedAt, egg, ...(origin ? { origin } : {}),
})
}
/** Easter words used, as hashes. A word stored before words were hashed reads as its hash; a seed keeps
* only the hashes this roster knows. */
function parseEaster(raw: unknown, strict: boolean): string[] {
if (!Array.isArray(raw)) return []
const out: string[] = []
for (const item of raw) {
if (typeof item !== 'string' || item.length < 1 || item.length > 64) continue
const hash = HASH_RE.test(item) ? item : easterHash(item)
if ((strict && !EASTER_HASHES.has(hash)) || out.includes(hash)) continue
out.push(hash)
if (out.length >= 64) break
}
return out
}
/**
* The zoo as stored (Json), validated entry by entry; anything malformed is dropped rather than served.
*
* `roster: true` (a guest's seed) also drops what the roster does not know: daemons, egg kinds,
* habits and words. A STORED zoo keeps a well-formed daemon id the roster lacks — a roster rolled back
* must not delete someone's daemon on their next write.
*
* A zoo stored before individuals (one record per species, duplicates merged into its `dupes`, `pair` a
* species id) reads as individuals: each record one, with `legacyUid(userId, id)` (a second record of one
* species, from before duplicates merged, its own), and `paired` the first individual of the old pair's
* species. The next write stores it in the new shape, with the same uids: reading it again changes nothing.
*/
export function parseZoo(raw: unknown, opts: { roster?: boolean; userId?: string } = {}): Zoo {
const src = record(raw)
const strict = !!opts.roster
const daemons: ZooDaemon[] = []
if (Array.isArray(src.daemons)) {
const nth = new Map<string, number>()
for (const item of src.daemons) {
if (daemons.length >= ZOO_MAX_DAEMONS) break
const d = readDaemon(item, opts.userId ?? '', nth)
if (!d || daemons.some((x) => x.uid === d.uid)) continue
if (strict && (!ROSTER_IDS.has(d.id) || !eggRule(d.egg))) continue
daemons.push(d)
}
}
const eggs: ZooEgg[] = []
if (Array.isArray(src.eggs)) {
for (const item of src.eggs) {
const parsed = zooEggSchema.safeParse(item)
if (!parsed.success || eggs.some((e) => e.id === parsed.data.id)) continue
if (strict && !eggRule(parsed.data.kind)) continue
eggs.push(parsed.data)
if (eggs.length >= ZOO_MAX_EGGS) break
}
}
// `paired` names a uid; a zoo from before individuals said `pair`, a species id.
const paired = Object.hasOwn(src, 'paired')
? (typeof src.paired === 'string' && daemons.some((d) => d.uid === src.paired) ? src.paired : null)
: (typeof src.pair === 'string' ? daemons.find((d) => d.id === src.pair)?.uid ?? null : null)
const consent = record(src.consent)
return {
daemons,
eggs,
paired,
autonomy: isAutonomy(src.autonomy) ? src.autonomy : ZOO_DEFAULT_AUTONOMY,
consent: typeof consent.watching === 'boolean' && typeof consent.at === 'string' && isoTime.safeParse(consent.at).success
? { watching: consent.watching, at: consent.at } : null,
habits: uniqueStrings(src.habits, (h) => !strict || HABIT_KEYS.has(h), 64),
firstEgg: src.firstEgg === true,
setupEgg: src.setupEgg === true,
pity: wholeIn(src.pity, ZOO_MAX_PITY),
sinceNew: wholeIn(src.sinceNew, ZOO_MAX_PITY),
easter: parseEaster(src.easter, strict),
progress: parseProgress(src.progress, strict),
}
}
// ── The draw ─────────────────────────────────────────────────────────────────────────────────────
/** Weights are whole units so `randomInt` can draw them exactly; a millionth is far below any odds. */
const WEIGHT_UNITS = 1_000_000
/**
* Whether this zoo's next hatch owes a species it does not own: one of its first `ZOO_FIRST_NEW` hatches
* (while the egg could give any new species), or the next after `ZOO_NEW_AFTER` in a row with none (while
* an unowned released regular exists). A zoo's individuals are its hatches: none is ever taken away.
*/
function owesNew(zoo: Zoo, fresh: number, secrets: number): boolean {
return (zoo.daemons.length < ZOO_FIRST_NEW && fresh + secrets > 0) || (zoo.sinceNew >= ZOO_NEW_AFTER && fresh > 0)
}
/**
* Who can come out of an egg of `kind` for this zoo at `now`, and how likely, in whole units (README,
* "The draw"):
*
* 1. Eligible: every released regular (not a secret), owned or not: a species you own hatches again as
* one more individual. Secrets sit outside the set: an unowned released secret is eligible, but only
* from an egg whose `weights.secret` is above 0; one you own never comes again.
* 2. Weight: `weights[rarity] / (eligible of that rarity)`, plus `pity * pityPerMiss` for a secret,
* times `boost[id]`. A rarity with no eligible daemon gives its weight to nothing.
* 3. The pity guarantee: from an egg that can hold a secret, when `pity` is one short of
* `secretGuaranteeAt` and a released secret is unowned, only the unowned secrets are eligible.
* 4. A new species owed (`owesNew`): only the species you do not own are eligible — the unowned
* regulars and, from an egg that can hold one, the unowned secrets — weighed as in 2.
*
* When what 4 leaves weighs nothing (an easter egg, which gives only legendaries and secrets, once those
* are owned) the egg draws as usual, and a new species is still owed to the next hatch. An egg whose
* eligible daemons all weigh nothing draws from every released daemon rather than giving nobody.
*/
export function drawWeights(zoo: Zoo, kind: string, now: Date = new Date()): Array<{ id: string; rarity: string; weight: number }> {
const egg = eggRule(kind)
if (!egg) return []
const secretsToo = holdsSecret(kind)
const released = releasedDaemons(now)
const owned = new Set(zoo.daemons.map((d) => d.id))
const regulars = released.filter((d) => d.rarity !== 'secret')
const fresh = regulars.filter((d) => !owned.has(d.id))
const secrets = secretsToo ? released.filter((d) => d.rarity === 'secret' && !owned.has(d.id)) : []
const weigh = (pool: readonly RosterDaemon[]) => {
const perRarity = new Map<string, number>()
for (const d of pool) perRarity.set(d.rarity, (perRarity.get(d.rarity) ?? 0) + 1)
return pool.map((d) => {
const base = (egg.weights[d.rarity] ?? 0) / perRarity.get(d.rarity)!
const pity = d.rarity === 'secret' && secretsToo ? zoo.pity * RULES.pityPerMiss : 0
const boost = egg.boost && Object.hasOwn(egg.boost, d.id) ? egg.boost[d.id] : 1
return { id: d.id, rarity: d.rarity, weight: Math.round((base + pity) * boost * WEIGHT_UNITS) }
})
}
const weighs = (weights: ReturnType<typeof weigh>) => weights.some((w) => w.weight > 0)
if (secrets.length && zoo.pity + 1 >= RULES.secretGuaranteeAt) return weigh(secrets)
if (owesNew(zoo, fresh.length, secrets.length)) {
const unowned = new Set([...fresh, ...secrets])
const weights = weigh(released.filter((d) => unowned.has(d)))
if (weighs(weights)) return weights
}
const eligible = new Set([...regulars, ...secrets])
const weights = weigh(released.filter((d) => eligible.has(d)))
return weighs(weights) ? weights : weigh(released)
}
/** One draw: which species hatches, then (independently) whether it is shiny. `rng` is called in that
* order. (The hatch then draws the individual's seed and uid: see `hatchOne`.) */
export function draw(zoo: Zoo, kind: string, rng: Rng, now: Date = new Date()): { id: string; rarity: string; shiny: boolean } | null {
const weights = drawWeights(zoo, kind, now)
const total = weights.reduce((sum, w) => sum + w.weight, 0)
if (total <= 0) return null
let at = rng(total)
let picked = weights[weights.length - 1]
for (const w of weights) {
if (at < w.weight) { picked = w; break }
at -= w.weight
}
return { id: picked.id, rarity: picked.rarity, shiny: rng(RULES.shinyOneIn) === 0 }
}
/**
* The daemon a history egg from `date` gives: that date's daemon from `rules.historyDates`, when a
* released drop holds it and you do not own it yet. Otherwise null, and the egg draws like any other.
*/
export function historyDaemon(zoo: Zoo, date: string | undefined, now: Date = new Date()): RosterDaemon | null {
if (!date) return null
const mmdd = date.slice(5)
const id = Object.hasOwn(HISTORY_DATES, mmdd) ? HISTORY_DATES[mmdd] : null
if (!id || zoo.daemons.some((d) => d.id === id)) return null
return releasedDaemons(now).find((d) => d.id === id) ?? null
}
/** The draw for one egg: a history egg's own daemon when it has one to give, else the usual draw. */
function drawEgg(zoo: Zoo, egg: ZooEgg, rng: Rng, now: Date): { id: string; rarity: string; shiny: boolean } | null {
const own = egg.kind === 'history' ? historyDaemon(zoo, egg.date, now) : null
if (own) return { id: own.id, rarity: own.rarity, shiny: rng(RULES.shinyOneIn) === 0 }
return draw(zoo, egg.kind, rng, now)
}
// ── Ops ──────────────────────────────────────────────────────────────────────────────────────────
const EGG_ID_ALPHABET = 'abcdefghijkmnpqrstuvwxyz23456789' // 32 symbols: no 0/o, 1/l
const EGG_ID_LENGTH = 10 // 50 bits: an id is never reused in practice
/** What one request produced besides the zoo itself. */
interface Outcome { hatched: Hatched[]; grants: Grant[]; levelUps: LevelUp[] }
/** What the route knows that the document does not. */
export interface ZooContext {
/** Whether a machine id is one of the account's machines. Only those count as a machine seen (the
* second-machine marathon egg); every reported turn counts either way. Absent: every id counts. */
ownsMachine?: (machineId: string) => boolean
}
/** A fresh egg id, unlike any egg in the zoo. Random, so a replayed hatch of an egg long gone can never
* land on a new egg that happens to share its name. */
function newEggId(zoo: Pick<Zoo, 'eggs'>, rng: Rng): string {
for (;;) {
let id = ''
for (let i = 0; i < EGG_ID_LENGTH; i++) id += EGG_ID_ALPHABET[rng(EGG_ID_ALPHABET.length)]
if (!zoo.eggs.some((e) => e.id === id)) return id
}
}
function grantEgg(zoo: Zoo, kind: string, rng: Rng, now: Date, out: Outcome, date?: string): boolean {
if (zoo.eggs.length >= ZOO_MAX_EGGS) return false
const egg: ZooEgg = { id: newEggId(zoo, rng), kind, grantedAt: now.toISOString(), ...(date ? { date } : {}) }
zoo.eggs.push(egg)
out.grants.push({ kind, eggId: egg.id })
return true
}
const UID_WORDS = 3 // three 32-bit draws: 24 hex, 96 bits
const UID_WORD = 0x1_0000_0000
/** A fresh uid, unlike any individual's in the zoo. */
function newUid(zoo: Pick<Zoo, 'daemons'>, rng: Rng): string {
for (;;) {
let uid = ''
for (let i = 0; i < UID_WORDS; i++) uid += rng(UID_WORD).toString(16).padStart(8, '0')
if (!zoo.daemons.some((d) => d.uid === uid)) return uid
}
}
/** A hatch's seed: a whole number from 1 to `ZOO_SEED_MAX` (0 is kept for the default traits). */
const newSeed = (rng: Rng): number => 1 + rng(ZOO_SEED_MAX)
/** xp for one individual; a new level bumps bond and version and is answered in `levelUps`. */
function grow(d: ZooDaemon, xp: number, out: Outcome): void {
if (xp <= 0) return
d.xp = Math.min(d.xp + xp, ZOO_MAX_XP)
const level = levelFor(d.xp)
if (level <= d.bond) return
d.bond = level
d.version = versionFor(level)
out.levelUps.push({ uid: d.uid, id: d.id, level, version: d.version })
}
/** The paired individual. */
const pairedDaemon = (zoo: Zoo): ZooDaemon | undefined => zoo.paired === null ? undefined : zoo.daemons.find((x) => x.uid === zoo.paired)
/** xp for the paired daemon. Nothing without a pair. */
function addXp(zoo: Zoo, xp: number, out: Outcome): void {
const d = pairedDaemon(zoo)
if (d) grow(d, xp, out)
}
/** An egg earned from work. It joins the queue of held eggs, which `releaseHeld` empties into the nest
* while there is room — so an egg earned with a full nest waits its turn instead of being lost. Past
* 64 held it becomes `rules.overflowXp` for the paired daemon, answered as a grant with its `xp` (with
* nothing paired, nothing has hatched to grow, and it is lost). */
function earnEgg(zoo: Zoo, kind: string, out: Outcome, date?: string): void {
if (zoo.progress.held.length < ZOO_MAX_HELD) {
zoo.progress.held.push(date ? { kind, date } : { kind })
return
}
const d = pairedDaemon(zoo)
if (!d) return
grow(d, RULES.overflowXp, out)
out.grants.push({ kind, xp: RULES.overflowXp })
}
/** Held eggs into the nest, oldest first, while there is room. Runs after every op, so a hatch that
* frees a place lets the next waiting egg in. */
function releaseHeld(zoo: Zoo, rng: Rng, now: Date, out: Outcome): boolean {
let changed = false
while (zoo.progress.held.length && zoo.eggs.length < ZOO_MAX_EGGS) {
const next = zoo.progress.held.shift()!
grantEgg(zoo, next.kind, rng, now, out, next.date)
changed = true
}
return changed
}
/**
* The eggs habits earn, each once: the first egg at `firstEgg.need` habits, one of them every habit in
* `firstEgg.require` (a finished turn); then the setup egg at `setupEgg.need`. Checked on every habit op,
* so a grant that found the nest full happens on the next one.
*/
function maybeGrantHabitEggs(zoo: Zoo, rng: Rng, now: Date, out: Outcome): boolean {
const done = zoo.habits.filter((h) => HABIT_KEYS.has(h))
let changed = false
if (!zoo.firstEgg && done.length >= RULES.firstEgg.need && FIRST_REQUIRES.every((k) => done.includes(k))) {
if (grantEgg(zoo, 'first', rng, now, out)) { zoo.firstEgg = true; changed = true }
}
if (zoo.firstEgg && !zoo.setupEgg && done.length >= RULES.setupEgg.need) {
if (grantEgg(zoo, 'setup', rng, now, out)) { zoo.setupEgg = true; changed = true }
}
return changed
}
/** Whether a reported local day can be today somewhere on Earth (UTC-12 to UTC+14), or is at most
* `ZOO_TURN_LATE_DAYS` later than that. */
function dayInWindow(day: string, now: Date): boolean {
const today = Math.floor(now.getTime() / DAY_MS)
const at = dayNumber(day)
return at >= today - 1 - ZOO_TURN_LATE_DAYS && at <= today + 1
}
type TurnOp = Extract<ZooOp, { op: 'zoo.turn' }>
/**
* Turns finished on one machine (README, "Earning eggs and growing"). A turn counts once, and once more
* for every `earn.turn.minutesPerTurn` agent-minutes the batch ran. In order: the daily cap decides how
* many count; counted turns earn turn eggs, the 500-turn marathon egg, a worked day toward the week egg,
* a night toward the night egg (a turn that finished while you were away, in the night hours), and the
* egg of a history date whose week is open; the paired daemon gets xp for each and for the first counted
* turn of the day. A machine seen may earn the second-machine marathon egg.
*/
function applyTurn(zoo: Zoo, op: TurnOp, now: Date, out: Outcome, ctx: ZooContext): boolean {
const p = zoo.progress
if (p.batches.includes(op.batchId) || !dayInWindow(op.day, now)) return false
let changed = false
const machines = EARN.marathon.machines
if (!p.machines.includes(op.machineId) && p.machines.length < machines && (ctx.ownsMachine?.(op.machineId) ?? true)) {
p.machines.push(op.machineId)
changed = true
if (p.machines.length >= machines && !p.marathon.includes('machines')) {
p.marathon.push('machines')
earnEgg(zoo, 'marathon', out)
}
}
const before = p.days[op.day] ?? 0
const units = op.n + Math.floor((op.minutes ?? 0) / EARN.turn.minutesPerTurn)
const counted = Math.max(0, Math.min(units, EARN.turn.dailyCap - before))
if (counted > 0) {
changed = true
p.days[op.day] = before + counted
pruneDays(p.days)
const turnsBefore = p.turns
p.turns = Math.min(p.turns + counted, ZOO_MAX_TURNS)
const every = EARN.turn.every
for (let k = Math.floor(turnsBefore / every); k < Math.floor(p.turns / every); k++) earnEgg(zoo, 'turn', out)
if (p.turns >= EARN.marathon.turns && !p.marathon.includes('turns')) {
p.marathon.push('turns')
earnEgg(zoo, 'marathon', out)
}
const week = isoWeek(op.day)
if (!p.weeks.includes(week) && Object.keys(p.days).filter((d) => isoWeek(d) === week).length >= EARN.week.days) {
p.weeks = [...p.weeks, week].slice(-WEEK_MEMORY)
earnEgg(zoo, 'week', out)
}
const night = (op.away ?? 0) > 0 ? nightOf(op.day, op.hour) : null
if (night && !p.nights.includes(night)) {
p.nights.push(night)
if (p.nights.length >= EARN.night.nights) {
p.nights = []
earnEgg(zoo, 'night', out)
}
}
for (const date of historyDatesOpen(op.day)) {
if (p.history.includes(date)) continue
p.history = [...p.history, date].slice(-HISTORY_MEMORY)
earnEgg(zoo, 'history', out, date)
}
addXp(zoo, counted * RULES.bond.xpPerTurn + (before === 0 ? RULES.bond.xpPerDay : 0), out)
}
// A batch that changed nothing (the day's cap was already reached) is not remembered: replayed, it
// still changes nothing, and not writing it spares every client a re-fetch each minute past the cap.
if (changed) p.batches = [...p.batches, op.batchId].slice(-ZOO_BATCH_MEMORY)
return changed
}
type LessonOp = Extract<ZooOp, { op: 'zoo.lesson' }>
/**
* A lesson the person approved (daemons/LEARNING.md, "The zoo"): `rules.lessonXp` for the daemon that
* found it when you own it, else for the paired one (the finder may be a guest's daemon that never came
* along to this account). The report names a species: the paired individual when it is of that species
* (the pair brain found it), else the first of that species hatched. Once per lesson id: a retry of a
* report that landed grows nothing. With neither, nothing grows and the id is not remembered.
*/
function applyLesson(zoo: Zoo, op: LessonOp, out: Outcome): boolean {
const p = zoo.progress
if (p.lessons.includes(op.lessonId)) return false
const paired = pairedDaemon(zoo)
const d = (paired?.id === op.daemonId ? paired : zoo.daemons.find((x) => x.id === op.daemonId)) ?? paired
if (!d) return false
grow(d, RULES.lessonXp, out)
p.lessons = [...p.lessons, op.lessonId].slice(-ZOO_LESSON_MEMORY)
return true
}
const isEmpty = (zoo: Zoo): boolean => zoo.daemons.length === 0 && zoo.eggs.length === 0 && zoo.habits.length === 0
/** The only eggs a guest's seed brings: the first egg and turn eggs, neither of which can hold a secret. */
const SEEDED_EGGS: ReadonlySet<string> = new Set(['first', 'turn'])
const cloneProgress = (p: ZooProgress): ZooProgress => ({
turns: p.turns,
days: { ...p.days },
weeks: [...p.weeks],
nights: [...p.nights],
machines: [...p.machines],
marathon: [...p.marathon],
history: [...p.history],
held: p.held.map((h) => ({ ...h })),
batches: [...p.batches],
lessons: [...p.lessons],
})
const clone = (zoo: Zoo): Zoo => ({
daemons: zoo.daemons.map((d) => ({ ...d })),
eggs: zoo.eggs.map((e) => ({ ...e })),
paired: zoo.paired,
autonomy: zoo.autonomy,
consent: zoo.consent ? { ...zoo.consent } : null,
habits: [...zoo.habits],
firstEgg: zoo.firstEgg,
setupEgg: zoo.setupEgg,
pity: zoo.pity,
sinceNew: zoo.sinceNew,
easter: [...zoo.easter],
progress: cloneProgress(zoo.progress),
})
type HatchOp = Extract<ZooOp, { op: 'zoo.hatch' }>
/**
* Hatch one egg: draw the species (and shiny), then the individual's seed and uid, in that order of
* `rng` calls. Every hatch is a new individual — a species you own too — at 0.1, paired when nothing is.
* A full zoo (`ZOO_MAX_DAEMONS`) hatches nothing and the egg stays where it is.
*/
function hatchOne(zoo: Zoo, op: HatchOp, rng: Rng, now: Date, out: Outcome): boolean {
const i = zoo.eggs.findIndex((e) => e.id === op.eggId)
if (i < 0 || zoo.daemons.length >= ZOO_MAX_DAEMONS) return false
const egg = zoo.eggs[i]
const drawn = drawEgg(zoo, egg, rng, now)
if (!drawn) return false // a kind this roster cannot draw
const isNew = !zoo.daemons.some((d) => d.id === drawn.id)
zoo.eggs.splice(i, 1)
// The pity counts only hatches that could have been a secret.
if (drawn.rarity === 'secret') zoo.pity = 0
else if (holdsSecret(egg.kind)) zoo.pity = Math.min(zoo.pity + 1, ZOO_MAX_PITY)
zoo.sinceNew = isNew ? 0 : Math.min(zoo.sinceNew + 1, ZOO_MAX_PITY)
const seed = newSeed(rng)
const d: ZooDaemon = {
uid: newUid(zoo, rng), id: drawn.id, seed, shiny: drawn.shiny, xp: 0, bond: 0, version: FIRST_VERSION,
hatched: now.toISOString(), egg: egg.kind,
}
zoo.daemons.push(d)
if (zoo.paired === null) zoo.paired = d.uid
out.hatched.push({ eggId: egg.id, daemonId: d.id, ...d })
return true
}
/**
* Apply one op to `zoo` IN PLACE (applyZooOps hands it a copy). Returns whether anything changed; what
* it hatched, granted or levelled goes into `out`.
*
* Every hatch is its own individual; `zoo.pair` and `zoo.nickname` name one by its uid.
*/
function applyZooOp(zoo: Zoo, op: ZooOp, rng: Rng, now: Date, out: Outcome, ctx: ZooContext): boolean {
switch (op.op) {
case 'zoo.habit': {
if (!HABIT_KEYS.has(op.key)) return false
let changed = false
if (!zoo.habits.includes(op.key)) { zoo.habits.push(op.key); changed = true }
if (maybeGrantHabitEggs(zoo, rng, now, out)) changed = true
return changed
}
case 'zoo.hatch':
return hatchOne(zoo, op, rng, now, out)
case 'zoo.pair': {
if (zoo.paired === op.uid || !zoo.daemons.some((d) => d.uid === op.uid)) return false
zoo.paired = op.uid
return true
}
// The dial and consent are plain assignments, in the order the person made them; what they changed is
// settled once the whole request has run (settleConsent), never per op. See applyZooOps.
case 'zoo.autonomy': {
if (isAutonomy(op.level)) zoo.autonomy = op.level
return false
}
case 'zoo.consent': {
// Agreeing to be watched starts at `watch`, every time — agreeing again too: the person opts into
// `suggest` and above afterwards, with a dial move made after the yes. Saying no leaves the dial where
// it is (nothing is sensed), and a later yes starts at `watch` again, so a level held before a no is
// never raised again by the yes that follows it.
if (op.watching) zoo.autonomy = 'watch'
zoo.consent = { watching: op.watching, at: zoo.consent?.at ?? '' }
return false
}
case 'zoo.nickname': {
const d = zoo.daemons.find((x) => x.uid === op.uid)
if (!d || (d.name ?? null) === op.name) return false
if (op.name === null) delete d.name
else d.name = op.name
return true
}
case 'zoo.easter': {
const hash = easterHash(op.word)
if (!EASTER_HASHES.has(hash) || zoo.easter.includes(hash)) return false
// A full nest leaves the word unspent, so saying it again later still works.
if (!grantEgg(zoo, 'easter', rng, now, out)) return false
zoo.easter.push(hash)
return true
}
case 'zoo.seed': {
if (!isEmpty(zoo)) return false
const seed = parseZoo(op.zoo, { roster: true })
// A guest's zoo lived on a client: everything in it is self-reported. What comes in is only what a
// client could not have made valuable — its individuals of regular species, each fresh at 0.1 with
// the species' default traits (seed 0: no rolled look, no shiny, no xp, no bond, no serial), the
// first and turn eggs, and the habits — all marked `local`. Pity, secrets, the eggs that can hold one
// (night, easter), easter words, progress, the dial and consent stay the account's own. A daemon of a
// drop not yet released could not have hatched anywhere, so it stays out too. Uids and egg ids are
// the server's to give: each is made new on the way in.
const regular = new Set(releasedDaemons(now).filter((d) => d.rarity !== 'secret').map((d) => d.id))
const came = seed.daemons.filter((d) => regular.has(d.id))
const daemons: ZooDaemon[] = []
for (const d of came) {
daemons.push({
uid: newUid({ daemons }, rng), id: d.id, seed: 0, ...(d.name ? { name: d.name } : {}),
shiny: false, xp: 0, bond: 0, version: FIRST_VERSION, hatched: d.hatched, egg: d.egg, origin: 'local',
})
}
const kept = seed.eggs.filter((e) => SEEDED_EGGS.has(e.kind))
if (!daemons.length && !kept.length && !seed.habits.length) return false
const eggs: ZooEgg[] = []
for (const egg of kept) eggs.push({ id: newEggId({ eggs }, rng), kind: egg.kind, grantedAt: egg.grantedAt, origin: 'local' })
const pairedAt = came.findIndex((d) => d.uid === seed.paired)
const paired = (pairedAt >= 0 ? daemons[pairedAt] : daemons[0])?.uid ?? null
Object.assign(zoo, { daemons, eggs, paired, habits: seed.habits, firstEgg: seed.firstEgg, setupEgg: seed.setupEgg, pity: 0, sinceNew: 0, easter: [] })
return true
}
case 'zoo.turn':
return applyTurn(zoo, op, now, out, ctx)
case 'zoo.lesson':
return applyLesson(zoo, op, out)
}
}
/**
* The dial and consent after a request, from what they were before it: consent's time moves only when the
* request as a whole changed the answer, and what changed is counted once, net. Whether the request moved
* them is what they are now against what they were — never whether some op along the way touched them.
*
* That is what makes a request that answers consent and moves the dial land in the same place however
* often it is delivered (a retry after a lost answer, a writer that lost the compare-and-set): each op is
* an assignment, so the dial ends at the last move the person made — a level, or `watch` for a yes — and
* consent at their last answer, whatever the zoo held when the request arrived.
*/
function settleConsent(before: Zoo, next: Zoo, now: Date): boolean {
const was = before.consent
const is = next.consent
if (is && is.watching !== was?.watching) next.consent = { watching: is.watching, at: now.toISOString() }
else next.consent = was ? { ...was } : null
return next.autonomy !== before.autonomy || next.consent?.watching !== was?.watching
}
/** Apply `ops` in order to a copy of `zoo`. `changed` is false when every op was a no-op — the same
* request twice, or ops on things already gone — and then nothing needs writing. After every op any
* held egg that now fits is let into the nest. */
export function applyZooOps(
zoo: Zoo, ops: ZooOp[], rng: Rng = cryptoRng, now: Date = new Date(), ctx: ZooContext = {},
): { changed: boolean; zoo: Zoo } & Outcome {
const next = clone(zoo)
const out: Outcome = { hatched: [], grants: [], levelUps: [] }
let changed = false
for (const op of ops) {
if (applyZooOp(next, op, rng, now, out, ctx)) changed = true
if (releaseHeld(next, rng, now, out)) changed = true
}
if (settleConsent(zoo, next, now)) changed = true
return { changed, zoo: next, ...out }
}