iCode-TUI 0.29.1__py3-none-any.whl

chrys/app/features/buddy/animation.py

@@ -0,0 +1,76 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Timing for the three pixel poses, independent of artwork and terminal rendering."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from chrys.app.features.buddy.model import Species
+
+IDLE_FRAME_COUNT = 3
+FRAME_COUNT = IDLE_FRAME_COUNT * 2
+# Eyelids keep their own time. The period shares no factor with any temperament's, so a blink lands on a
+# different moment of the rhythm each time instead of becoming part of it.
+_BLINK_EVERY_TICKS = 13
+
+
+@dataclass(frozen=True)
+class _Temperament:
+    """How a species idles: it rests, then stretches through its two other poses, holding each one."""
+
+    rest_ticks: int
+    hold_ticks: int
+
+    def pose(self, tick: int) -> int:
+        """The idle pose at *tick*: 0 while resting, then 1 and 2 for *hold_ticks* each."""
+        into_stretch = tick % (self.rest_ticks + 2 * self.hold_ticks) - self.rest_ticks
+        return 0 if into_stretch < 0 else 1 + into_stretch // self.hold_ticks
+
+
+_DARTING = _Temperament(rest_ticks=2, hold_ticks=1)
+_LIVELY = _Temperament(rest_ticks=5, hold_ticks=1)
+_EASY = _Temperament(rest_ticks=8, hold_ticks=2)
+_SLOW = _Temperament(rest_ticks=14, hold_ticks=3)
+
+# How restless each species is. The rhythm comes from the temperament, never from a per-species cue list.
+_TEMPERAMENTS: dict[Species, _Temperament] = {
+    Species.ALIEN: _LIVELY,
+    Species.AXOLOTL: _EASY,
+    Species.BAT: _LIVELY,
+    Species.BEE: _DARTING,
+    Species.CACTUS: _SLOW,
+    Species.CAPYBARA: _SLOW,
+    Species.CAT: _EASY,
+    Species.CRAB: _LIVELY,
+    Species.DRAGON: _LIVELY,
+    Species.DUCK: _EASY,
+    Species.FOX: _LIVELY,
+    Species.FROG: _LIVELY,
+    Species.GHOST: _EASY,
+    Species.GOOSE: _EASY,
+    Species.JELLY: _EASY,
+    Species.LLAMA: _EASY,
+    Species.MUSHROOM: _SLOW,
+    Species.OCTOPUS: _LIVELY,
+    Species.OWL: _EASY,
+    Species.PANDA: _SLOW,
+    Species.PENGUIN: _EASY,
+    Species.RABBIT: _LIVELY,
+    Species.ROBOT: _LIVELY,
+    Species.SHARK: _DARTING,
+    Species.SNAIL: _SLOW,
+    Species.SNAKE: _DARTING,
+    Species.TABBY: _EASY,
+    Species.TURTLE: _SLOW,
+}
+
+
+def get_idle_frame(species: Species, tick: int) -> tuple[int, bool]:
+    """Choose an idle pixel pose and eyelid state for the current tick."""
+    return _TEMPERAMENTS[species].pose(tick), tick % _BLINK_EVERY_TICKS == _BLINK_EVERY_TICKS - 1
+
+
+def get_pet_frame(tick: int) -> int:
+    """Cycle the three intact petting poses at the caller's faster cadence."""
+    return IDLE_FRAME_COUNT + tick % IDLE_FRAME_COUNT

chrys/app/features/buddy/commands.py

@@ -0,0 +1,196 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""The ``/buddy`` command: what each subcommand does and what it answers.
+
+Everything here answers at once. The TUI can wait for a model, so it answers ``/buddy pet``
+itself, after :func:`pet_refusal`, and never asks for it here. Asked here anyway, petting is
+counted and gets a stock line.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Literal
+
+from rich.cells import cell_len
+
+from chrys.app.features.buddy import actions
+from chrys.app.features.buddy.model import TRAIT_MAX, Trait, clean_name
+from chrys.app.features.buddy.replies import stock_reply
+from chrys.foundation.i18n import DisplayBlock, MessageRef, msg
+from chrys.foundation.i18n.formatting import format_message
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from chrys.app.features.buddy.model import Buddy
+
+logger = logging.getLogger(__name__)
+
+_GAUGE_CELLS = 10
+
+type Severity = Literal["information", "warning"]
+type CommandAnswer = tuple[MessageRef | str, Severity]
+# The card is text put together here, so the persona line inside it is rendered here, by the caller's renderer.
+type Render = Callable[[MessageRef], str]
+
+_NO_BUDDY_TO_PET = msg(
+    "tui.buddy.no_buddy_to_pet",
+    fallback="There is nobody to pet yet. Hatch a buddy with /buddy hatch.",
+)
+_BUDDY_MUTED = msg(
+    "tui.buddy.muted",
+    fallback="{name} is muted and stays quiet. Use /buddy mute to hear from it again.",
+)
+_INTRO_NO_BUDDY = msg(
+    "tui.buddy.intro_no_buddy",
+    fallback="🥚 There is an egg here, and nobody knows what is in it.\n\n/buddy hatch finds out.",
+    multiline=True,
+)
+_INTRO_WITH_BUDDY = msg(
+    "tui.buddy.intro_with_buddy",
+    fallback="🐾 {name} is keeping you company.\n\n/buddy info shows how it is doing, /buddy pet gives it a pat.",
+    multiline=True,
+)
+_NOT_HATCHED = msg("tui.buddy.not_hatched", fallback="No buddy has hatched yet. Start with /buddy hatch.")
+_HATCH_ALREADY = msg("tui.buddy.hatch_already", fallback="{name} is already here, and one buddy is all you get.")
+_HATCH_SUCCESS = msg(
+    "tui.buddy.hatch_success",
+    fallback="🐣 Out of the egg:\n\n{info}\n\nFrom now on it lives in the sidebar, on the Buddy tab.",
+    multiline=True,
+)
+_MUTE_ON = msg("tui.buddy.mute_on", fallback="Your buddy will keep quiet from now on. It is still around.")
+_MUTE_OFF = msg("tui.buddy.mute_off", fallback="Your buddy can speak up again.")
+_NAME_EMPTY = msg("tui.buddy.name_empty", fallback="Give the new name too, for example /buddy name Mochi")
+_NAME_SUCCESS = msg("tui.buddy.name_success", fallback="Your buddy answers to {name} now.")
+_SAVE_FAILED = msg(
+    "tui.buddy.save_failed",
+    fallback="The buddy save file could not be updated, so nothing has changed. Try again in a moment.",
+)
+_UNKNOWN_COMMAND = msg(
+    "tui.buddy.unknown",
+    fallback='/buddy does not know "{arg}".\n\nIt knows: hatch, info, pet, mute, name <new name>',
+    multiline=True,
+)
+# The card's labels. Species and rarity stay as they are spelled everywhere else.
+_CARD_SHINY = msg("tui.buddy.card.shiny", fallback="shiny")
+_CARD_LEVEL = msg("tui.buddy.card.level", fallback="level")
+_CARD_FULLY_GROWN = msg("tui.buddy.card.fully_grown", fallback="{level} · fully grown")
+_CARD_PROGRESS = msg("tui.buddy.card.progress", fallback="{level} · {xp}/{needed} XP")
+_CARD_TRAIT_FOCUS = msg("tui.buddy.card.trait.focus", fallback="focus")
+_CARD_TRAIT_CURIOSITY = msg("tui.buddy.card.trait.curiosity", fallback="curiosity")
+_CARD_TRAIT_GRIT = msg("tui.buddy.card.trait.grit", fallback="grit")
+_CARD_TRAIT_CHARM = msg("tui.buddy.card.trait.charm", fallback="charm")
+_CARD_SINCE = msg("tui.buddy.card.since", fallback="{hatched} · {turns} turns · {pets} pets")
+_CARD_EVOLUTION = msg("tui.buddy.card.evolution", fallback="evolution {stage}")
+_CARD_TRAITS = {
+    Trait.FOCUS: _CARD_TRAIT_FOCUS,
+    Trait.CURIOSITY: _CARD_TRAIT_CURIOSITY,
+    Trait.GRIT: _CARD_TRAIT_GRIT,
+    Trait.CHARM: _CARD_TRAIT_CHARM,
+}
+
+
+def split_command(arg: str | None) -> tuple[str, str]:
+    """``/buddy <arg>`` as a lower-case subcommand and whatever follows it. Any whitespace separates the two."""
+    verb, rest, *_ = [*(arg or "").split(None, 1), "", ""]
+    return verb.lower(), rest
+
+
+def pet_refusal(buddy: Buddy | None) -> CommandAnswer | None:
+    """Why *buddy* cannot be petted through the command right now, or None when it can."""
+    if buddy is None:
+        return _NO_BUDDY_TO_PET.bind(), "warning"
+    if buddy.muted:
+        return _BUDDY_MUTED.bind(name=buddy.display_name), "warning"
+    return None
+
+
+def handle_buddy_command(arg: str | None, *, render: Render = format_message) -> CommandAnswer:
+    """Carry out ``/buddy <arg>`` and say what happened. *render* puts the info card in the user's language."""
+    try:
+        return _carry_out(arg, render)
+    except OSError:  # a read-only or full config directory, or another instance wedged on the save file
+        logger.warning("Buddy save file could not be updated", exc_info=True)
+        return _SAVE_FAILED.bind(), "warning"
+
+
+def _carry_out(arg: str | None, render: Render) -> CommandAnswer:
+    buddy = actions.current_buddy()
+    verb, rest = split_command(arg)
+
+    if not verb:
+        if buddy is None:
+            return _INTRO_NO_BUDDY.bind(), "information"
+        return _INTRO_WITH_BUDDY.bind(name=buddy.display_name), "information"
+    if verb == "hatch":
+        if buddy is not None:
+            return _HATCH_ALREADY.bind(name=buddy.display_name), "warning"
+        return _HATCH_SUCCESS.bind(info=DisplayBlock(buddy_card(actions.hatch(), render=render))), "information"
+    if verb == "pet":
+        refusal = pet_refusal(buddy)
+        if refusal is not None:
+            return refusal
+        if buddy is None:
+            raise RuntimeError("Petting requires an existing buddy.")
+        actions.record_pet()
+        return stock_reply(buddy), "information"
+    if verb not in {"info", "mute", "name"}:
+        return _UNKNOWN_COMMAND.bind(arg=arg or ""), "warning"
+    if buddy is None:
+        return _NOT_HATCHED.bind(), "warning"
+    if verb == "info":
+        return buddy_card(buddy, render=render), "information"
+    if verb == "mute":
+        actions.set_muted(not buddy.muted)
+        return (_MUTE_OFF if buddy.muted else _MUTE_ON).bind(), "information"
+    name = clean_name(rest)
+    if not name:
+        return _NAME_EMPTY.bind(), "warning"
+    actions.rename(name)
+    return _NAME_SUCCESS.bind(name=name), "information"
+
+
+def buddy_card(buddy: Buddy, *, render: Render = format_message) -> str:
+    """*buddy* at a glance: who it is, how far it has come, what it is like, and since when."""
+    progress, record = buddy.progress, buddy.record
+    who = [buddy.display_name, buddy.species.value, buddy.rarity.value]
+    if buddy.shiny:
+        who.append(render(_CARD_SHINY.bind()))
+    if progress.maxed:
+        climb = f"{_gauge(1, 1)}  {render(_CARD_FULLY_GROWN.bind(level=buddy.level))}"
+    else:
+        into, needed = progress.xp_into_level, progress.xp_for_level
+        climb = f"{_gauge(into, needed)}  {render(_CARD_PROGRESS.bind(level=buddy.level, xp=into, needed=needed))}"
+    level_label = render(_CARD_LEVEL.bind())
+    trait_labels = {trait: render(_CARD_TRAITS[trait].bind()) for trait in Trait}
+    label_width = max(cell_len(label) for label in (level_label, *trait_labels.values()))
+    traits = buddy.traits
+    since = render(
+        _CARD_SINCE.bind(hatched=f"{record.hatched_at.astimezone():%Y-%m-%d}", turns=record.turns, pets=record.pets)
+    )
+    if buddy.evolved:
+        since += f" · {render(_CARD_EVOLUTION.bind(stage=progress.stage))}"
+    return "\n".join(
+        [
+            f"🐾 {' · '.join(who)}",
+            f"{_padded(level_label, label_width)}  {climb}",
+            *(
+                f"{_padded(trait_labels[trait], label_width)}  {_gauge(traits[trait], TRAIT_MAX)}  {traits[trait]}"
+                for trait in Trait
+            ),
+            f"“{render(buddy.persona)}”",
+            since,
+        ]
+    )
+
+
+def _padded(label: str, width: int) -> str:
+    # Padded by cells, not characters: a CJK label is two cells wide per character.
+    return label + " " * (width - cell_len(label))
+
+
+def _gauge(value: int, full: int) -> str:
+    # Rounded down: a gauge is full only when what it measures is.
+    filled = _GAUGE_CELLS * value // full
+    return "▰" * filled + "▱" * (_GAUGE_CELLS - filled)

chrys/app/features/buddy/docs/design.md

@@ -0,0 +1,187 @@
+# Buddy
+
+A buddy is a small pet that lives in the sidebar, grows as the user works, and
+answers in one line when it is petted. The package is split by concern:
+
+| Module | Owns |
+| --- | --- |
+| `model.py` | `BuddyRecord` (what is saved) and `Buddy` (the record plus everything derived from it) |
+| `hatchery.py` | The random draw that makes a new record |
+| `progression.py` | Experience, levels and evolution stages |
+| `store.py` | The save file: locking, atomic writes, the signed envelope |
+| `actions.py` | The changes a user can cause: hatch, rename, mute, pet, finish a turn |
+| `commands.py` | `/buddy` subcommands and the info card |
+| `replies.py` | The one-line answer to a pet, from a model or a stock line |
+| `lifecycle.py` | The hook every frontend calls, on its event loop, after a successful turn |
+| `sprites/*.toml`, `pixel_sprites.py`, `pixel_renderer.py`, `animation.py`, `portrait.py` | Artwork and its rendering |
+
+The TUI adds `app/tui/buddy_reply.py::PetReplyFlow`, which the sidebar panel and
+`/buddy pet` share: a thinking toast now, the answer when it arrives, and one
+reply in flight per process.
+
+## Hatching
+
+Hatching is a plain random draw (`random.SystemRandom` in production, any
+`random.Random` in tests) and the whole result is saved. Nothing about a buddy
+is derived from the machine or the user, so a buddy moves with its save file.
+
+The draw picks a rarity tier (`RARITY_ODDS`), a species that hatches in that
+tier, a 1-in-40 shiny flag, four traits (focus, curiosity, grit and charm) and
+a name. Each tier has a trait point budget (`TRAIT_POINTS`) that is shared out
+unevenly, so every buddy leans some way. The strongest trait at hatch time
+decides the persona line. It is a message like any other display text: the
+info card and the sidebar show it in the user's language, and the reply
+prompt, which is English throughout, is given the English line.
+
+`SPECIES_RARITY` sorts the species by how far from the back garden one would
+have to go to meet them: N lives outside the window (bee, cat, duck, snail),
+R takes a trip (fox, owl, penguin, shark), SR takes luck (axolotl, capybara,
+panda), and SSR is not from around here at all (alien, dragon, ghost, robot).
+
+## Progression
+
+A finished turn is worth 10 XP and a pet 2 XP. Only the first `5 × (turns + 1)`
+pets of a buddy's life count, so the pets a turn pays for are worth exactly as
+much as the turn itself: petting can at best double what working earns, and
+without work it stops paying after the first five. The allowance is cumulative:
+pets not given after one turn may be given after a later one.
+
+A stage is 99 level-ups. A level costs `10 × (10 + level // 10 + 2 × stage)`
+XP, which makes the first stage about 1,440 turns and each later stage about
+200 turns longer. Finishing a stage below the top rarity tier evolves the buddy
+one tier and restarts it at level 1; the top tier ends at level 100. Levels and
+stages are never stored. `progress()` derives them from the turn and pet
+counters, so changing the curve re-levels every buddy consistently.
+
+Traits grow by one point per ten levels and ten per evolution, capped at 100.
+A top-tier buddy that has evolved or reached the final level turns shiny.
+
+## Save file
+
+`<config dir>/extras/buddy/buddy.json`, shared by every running instance:
+
+```json
+{"v": 2, "buddy": {"species": "...", "rarity": "...", "...": "..."}, "sig": "<HMAC-SHA256>"}
+```
+
+Changes are read-modify-write under a lock file and land through an atomic
+replace, so readers take no lock. `buddy.json.bak` is a second copy that a
+reader falls back to. The signature uses a constant key: it catches damage and
+casual hand edits, and is not a secret. A file that does not verify, or that is
+not version 2, reads as "no buddy yet". Files written before version 2 are not
+migrated; those users hatch again.
+
+`BuddyRecord.from_json` accepts exactly what `to_json` writes and coerces
+nothing. Reading never raises. A change raises `OSError` when the file cannot
+be written (`TimeoutError` when another instance holds the lock for ten
+seconds): `/buddy` answers that with a warning, petting goes ahead uncounted,
+and the after-turn hook logs it. A muted buddy keeps its information toasts to
+itself, never a warning: a command that did not work is always reported. Until
+a buddy has hatched, no change touches the disk at all, so users who never
+hatch one pay nothing per turn.
+
+Waiting for the lock is never the event loop's job, since every frontend runs
+its turns, its input and its rendering there. The sidebar counts a pet on a
+widget worker, which its unmount cancels; `/buddy` commands run on a thread,
+one after another in the order they were given, and answer when they are done;
+and the after-turn hook hands the credit to the loop's default executor, which
+the loop's runner joins at exit, so a headless run still lands its last turn.
+A change whose task was cancelled still lands: a thread cannot be stopped, and
+the file is the truth either way. Reads take no lock and stay on the loop. A
+`/buddy pet` has two ends, the count and the answer, which finish in either
+order, and each one refreshes the panel in place when it does.
+
+# Pixel portraits
+
+All 28 species use a **20 × 16 RGBA canvas**, rendered as 20 terminal columns
+and eight rows of TrueColor half blocks (`▀`).
+
+## Artwork
+
+Artwork is data: each species has one `sprites/<species>.toml` file holding its
+`[palette]` (index → `[r, g, b, a]`) and three distinct poses as `[[frames]]`
+tables. Each pose's `rows` are 16 strings of 20 palette-index digits, which are
+not characters displayed to the user. `pixel_sprites.py` loads a file on first
+use and rejects one whose size or indices don't fit. Palette roles are `0` for
+transparency, `3` for the body shadow, and `4` for pupils; other colors belong
+to that species' design.
+
+Keep the silhouette recognizable at native size. Features that distinguish
+similar animals include:
+
+| Species | Defining features |
+| --- | --- |
+| Duck / goose | Flat orange bill; goose has a long neck |
+| Cat / tabby / fox | Pointed ears; tabby is rounder and wider; fox has a pale muzzle and large tail |
+| Rabbit | Long pink inner ears, dark pupils, cream muzzle, rounded haunches and paws, small round tail |
+| Owl / penguin | Owl's facial discs and ear tufts; penguin's pale belly and orange feet |
+| Turtle / snail | Turtle's domed shell and low legs; snail's spiral shell and eye stalks |
+| Octopus / axolotl | Tentacles; external gills and four small limbs |
+| Dragon / bat | Dragon's horns, belly and long tail; bat's broad wings |
+| Panda / capybara / llama | Dark eye patches; broad blunt muzzle; tall neck |
+| Shark / snake / frog | Dorsal fin and teeth; long coiled body; raised eyes and spread feet |
+| Bee / crab | Striped abdomen and wings; paired claws and spread legs |
+| Ghost / jelly / alien | Wavy hem; soft low body; large dome and dark eyes |
+| Cactus / mushroom / robot | Branched stem and pot; spotted cap and stalk; metal panels, LED eyes and antenna |
+
+Pupils retain their authored contrast color. Blinking changes only vertically
+stacked pupil pixels: upper pixels use the body shadow, while the bottom stays
+visible as a closed-eye line. Every built-in pose includes vertically stacked
+pupils so blinking visibly changes its expression. Isolated pupil pixels stay
+intact. Other features that happen to share an eye's RGB color must remain unchanged.
+
+## Animation and portrait layout
+
+`animation.py` owns timing for idle poses 0–2 and petting poses 3–5. Idling is
+a rule, not a list of cues: each species has a temperament (darting, lively,
+easy or slow), and a temperament is how long the animal rests and how long it
+holds a pose. It rests, stretches through pose 1 and then pose 2 for the same
+time each, and rests again, so every temperament has a period of its own.
+Eyelids keep their own time: one blink every 13 ticks whatever the pose, a
+period that shares no factor with any temperament's, so blinks never settle
+into the rhythm. Petting cycles all three poses faster. Its first pose hops up
+one pixel only when the top row is empty, preserving ears, horns and antennae.
+No particles or decorations overwrite the animal.
+
+`portrait.py` adds separate rarity-colored corners and a compact nameplate.
+Shiny animates only the badge. The portrait occupies 11 terminal rows at every
+width. Below 20 columns the complete pixel canvas is scaled with nearest-neighbor
+sampling and vertically padded, including custom PNG artwork. Built-in pupil
+pixels are retained at their scaled positions so single-column eyes stay visible. Corners are
+omitted below 22 columns so they do not crowd the animal.
+
+The sidebar repaints frames without invalidating layout, uses cached geometry,
+and skips offscreen portraits. The shiny badge runs on its own 10 Hz timer.
+
+The save file changes behind the panel's back: every finished turn credits it,
+and so does every other running instance. The panel reads it again when it
+comes into view and every few seconds while it stays there, and rewrites a
+label only when its text has changed, because each label update lays the whole
+screen out again.
+
+## Custom artwork
+
+Place PNG overrides at `~/.chrys/extras/buddy/assets/<species>_<frame>.png`, with
+frame indices 0–5. Images are normalized to 20 × 16 with nearest-neighbor
+sampling. Custom pixels are kept as supplied, including their eye design.
+File revisions invalidate a bounded image cache; missing or unreadable files
+fall back to built-in artwork and are retried on subsequent renders.
+
+When upgrading from 16 × 10, existing custom PNGs are stretched to the new
+20 × 16 canvas. Their aspect ratio therefore changes; redraw or export them
+at 20 × 16 to control their proportions. Two species were renamed: overrides
+called `blob_<frame>.png` or `chonk_<frame>.png` are no longer looked up and
+need renaming to `jelly_<frame>.png` and `tabby_<frame>.png`.
+
+## Preview and verification
+
+Run `uv run python playground/buddy.py` to inspect all species. Space pauses;
+`n`/`p` step ticks; `x` toggles petting; `s` toggles shiny; `t` cycles rarity;
+`b` forces blinking; `r` resets; `q` quits.
+
+Tests cover native dimensions and palettes, intact petting poses, pupil
+contrast, animation timing, narrow pixel rendering, PNG cache invalidation and
+mounted sidebar repaint behavior, plus the hatch draw, the progression curve,
+the save file envelope and its concurrency, commands and replies.
+`tests/app/tui/behaviors/test_buddy_sidebar_flow.py` drives `/buddy` through the
+real command controller, view adapter and sidebar.

chrys/app/features/buddy/hatchery.py

@@ -0,0 +1,80 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Hatching: one random draw, saved whole. Nothing about a buddy is derived from who the user is."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from chrys.app.features.buddy.model import BuddyRecord, Rarity, Species, Trait
+
+if TYPE_CHECKING:
+    from random import Random
+
+RARITY_ODDS: dict[Rarity, int] = {Rarity.N: 55, Rarity.R: 30, Rarity.SR: 12, Rarity.SSR: 3}
+
+SHINY_ODDS = 1 / 40
+
+# The tier each species hatches in, by how far from the back garden you would have to go to meet one:
+# N lives outside the window, R takes a trip, SR takes luck, SSR is not from around here at all.
+# Evolution moves a buddy up; it never changes species.
+SPECIES_RARITY: dict[Species, Rarity] = {
+    Species.ALIEN: Rarity.SSR,
+    Species.AXOLOTL: Rarity.SR,
+    Species.BAT: Rarity.R,
+    Species.BEE: Rarity.N,
+    Species.CACTUS: Rarity.R,
+    Species.CAPYBARA: Rarity.SR,
+    Species.CAT: Rarity.N,
+    Species.CRAB: Rarity.R,
+    Species.DRAGON: Rarity.SSR,
+    Species.DUCK: Rarity.N,
+    Species.FOX: Rarity.R,
+    Species.FROG: Rarity.N,
+    Species.GHOST: Rarity.SSR,
+    Species.GOOSE: Rarity.N,
+    Species.JELLY: Rarity.SR,
+    Species.LLAMA: Rarity.R,
+    Species.MUSHROOM: Rarity.N,
+    Species.OCTOPUS: Rarity.SR,
+    Species.OWL: Rarity.R,
+    Species.PANDA: Rarity.SR,
+    Species.PENGUIN: Rarity.R,
+    Species.RABBIT: Rarity.N,
+    Species.ROBOT: Rarity.SSR,
+    Species.SHARK: Rarity.R,
+    Species.SNAIL: Rarity.N,
+    Species.SNAKE: Rarity.N,
+    Species.TABBY: Rarity.N,
+    Species.TURTLE: Rarity.N,
+}
+
+# Trait points a hatchling of each tier has to share out. The largest possible share is half
+# the budget (see _share_out), so no budget here can push a trait past its maximum.
+TRAIT_POINTS: dict[Rarity, int] = {Rarity.N: 120, Rarity.R: 150, Rarity.SR: 180, Rarity.SSR: 200}
+
+NAMES = ("Byte", "Dot", "Miso", "Mochi", "Nori", "Pico", "Pixel", "Sprout", "Tofu", "Widget")
+
+
+def hatchling(rng: Random, *, now: datetime | None = None) -> BuddyRecord:
+    """Draw a new buddy from *rng*."""
+    rarity = rng.choices(list(RARITY_ODDS), weights=list(RARITY_ODDS.values()))[0]
+    return BuddyRecord(
+        species=rng.choice([species for species, home in SPECIES_RARITY.items() if home is rarity]),
+        rarity=rarity,
+        shiny=rng.random() < SHINY_ODDS,
+        traits=_share_out(rng, TRAIT_POINTS[rarity]),
+        name=rng.choice(NAMES),
+        hatched_at=now if now is not None else datetime.now(UTC),
+    )
+
+
+def _share_out(rng: Random, points: int) -> dict[Trait, int]:
+    """Split *points* between the traits unevenly, so every buddy leans some way.
+
+    An appetite is at most three times another, which bounds a share between a tenth and a half of *points*.
+    """
+    appetites = {trait: rng.uniform(0.5, 1.5) for trait in Trait}
+    unit = points / sum(appetites.values())
+    return {trait: round(appetite * unit) for trait, appetite in appetites.items()}

chrys/app/features/buddy/lifecycle.py

@@ -0,0 +1,41 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Buddy lifecycle callbacks for application entrypoints."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+from chrys.app.features.buddy.actions import record_turn
+
+if TYPE_CHECKING:
+    from chrys.app.features.buddy.model import Buddy
+
+logger = logging.getLogger(__name__)
+
+_FAILED = "Failed to credit the buddy with a turn"
+
+
+def on_successful_turn() -> None:
+    """Credit the buddy with a finished turn. A buddy must never be why a turn fails, or why it waits.
+
+    Every frontend finishes its turns on the event loop, and crediting waits for the save file's
+    lock, which another instance may hold for seconds. So the write goes to the loop's default
+    executor, which the loop's runner joins at exit, and the turn goes on at once.
+    """
+    try:
+        credit = asyncio.get_running_loop().run_in_executor(None, record_turn)
+    except Exception:
+        logger.debug(_FAILED, exc_info=True)
+        return
+    credit.add_done_callback(_log_a_failure)
+
+
+def _log_a_failure(credit: asyncio.Future[Buddy | None]) -> None:
+    if credit.cancelled():
+        return
+    failure = credit.exception()
+    if failure is not None:
+        logger.debug(_FAILED, exc_info=failure)