@crowdedkingdoms/ckx-kit 0.4.0-dev.1 → 0.5.0-dev.1

package/README.md

@@ -37,7 +37,7 @@ on the platform: Crowdy Studio, or `execModBuild` then `execModDeploy` (see
 
 | Command | What it does |
 |---|---|
-| `ckx-kit new <template> <name>` | A crate to start from: `mod`, `client` (a mod's CLIENT half), `hub`, `spoke`, or a starter pack crate (`world-tick`, `matchmaker`, `session`, `npc-mobs`, `leaderboard`, `deck`, `tactics`, `director`, `minigame`, `instance`, `arena`, `racing`, `territory`). |
+| `ckx-kit new <template> <name>` | A crate to start from: `mod`, `client` (a mod's CLIENT half), `hub`, `spoke`, or a starter pack crate (`world-tick`, `matchmaker`, `session`, `npc-mobs`, `leaderboard`, `deck`, `tactics`, `director`, `minigame`, `instance`, `arena`, `racing`, `territory`, `player`, `market`). |
 | `ckx-kit check [dir]` | The platform's source checks, on exactly the files it takes (`Cargo.toml`, `README.md`, `.rs` files under `src/`). Lists what it would not send. |
 | `ckx-kit build [dir]` | The checks, then the pinned Rust for `wasm32-unknown-unknown` with the platform's release profile and the platform's dependency versions, then the module check. `--mod` adds the mod limits. A CLIENT half is metered and optimized as the platform does it, and its capability summary, the list visitors are asked to agree to, is printed with its hash. `--json` prints a report. |
 | `ckx-kit doctor` | What a build here needs, and which platform toolchain this kit matches. |
@@ -55,7 +55,11 @@ random generator and the realtime event registry. The starter pack crates speak
 clients' typed modules drive them as they are. From `ckx-sdk` 0.11.0 it also has the pieces the
 genre starters are made of: `kit::play` (turns, scores, cards, combat, abilities, timing, a
 movement warden for positions clients report), `kit::sim` (day cycle, weather, resource nodes,
-waves, zones) and `kit::ai` (paths, flow fields, steering, behavior trees).
+waves, zones) and `kit::ai` (paths, flow fields, steering, behavior trees); from 0.12.0
+`kit::econ`, the soft economy the `player` and `market` starters keep in hub state: items,
+wallets, holds, references answered once, recipes, loot with pity, production, vendors, an
+order book, levels, achievements and quests. It is not a ledger: no real money, and a transfer
+between hubs is steps, not a transaction.
 
 ## Test
 

package/crates/ckx-sdk/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ckx-sdk"
-version = "0.11.0-dev.1"
+version = "0.12.1-dev.1"
 edition = "2024"
 description = "Write ck-exec hubs, spokes and mods for Crowded Kingdoms in Rust, compiled to wasm32-unknown-unknown"
 license = "MIT OR Apache-2.0"

package/crates/ckx-sdk/src/kit/econ/holdings.rs

@@ -0,0 +1,241 @@
+//! What a player owns: their inventory, their wallet, and the mail that holds items that did not
+//! fit ([`Holdings`]); and items and currency moved together ([`Bundle`]).
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+use super::check_id;
+use super::items::{Catalog, Inventory};
+use super::wallet::Wallet;
+use crate::Result;
+use crate::kit::{codes, error};
+
+/// Items and currency moved together: a price, a reward, a hold.
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq, Eq)]
+#[serde(default)]
+pub struct Bundle {
+    /// Item id to how many.
+    pub items: BTreeMap<String, u64>,
+    /// Currency to how much.
+    pub currency: BTreeMap<String, i64>,
+}
+
+impl Bundle {
+    pub fn item(id: &str, count: u64) -> Self {
+        Self { items: BTreeMap::from([(id.to_owned(), count)]), currency: BTreeMap::new() }
+    }
+
+    pub fn coins(currency: &str, amount: i64) -> Self {
+        Self { items: BTreeMap::new(), currency: BTreeMap::from([(currency.to_owned(), amount)]) }
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.items.values().all(|&n| n == 0) && self.currency.values().all(|&n| n == 0)
+    }
+
+    /// `bad_request` for an id the economy does not take or a negative amount.
+    pub fn check(&self) -> Result<()> {
+        for id in self.items.keys() {
+            check_id("item id", id)?;
+        }
+        for (id, &amount) in &self.currency {
+            check_id("currency", id)?;
+            if amount < 0 {
+                return Err(error(codes::BAD_REQUEST, "an amount is not negative"));
+            }
+        }
+        Ok(())
+    }
+
+    pub fn plus(&self, other: &Bundle) -> Result<Bundle> {
+        let mut out = self.clone();
+        for (id, &n) in &other.items {
+            let e = out.items.entry(id.clone()).or_insert(0);
+            *e = e.checked_add(n).ok_or_else(|| error(codes::LIMIT, "too many"))?;
+        }
+        for (id, &n) in &other.currency {
+            let e = out.currency.entry(id.clone()).or_insert(0);
+            *e = e.checked_add(n).ok_or_else(|| error(codes::LIMIT, "too much"))?;
+        }
+        Ok(out.trimmed())
+    }
+
+    /// What is left of `self` once `part` is taken out of it; `insufficient` when it holds less.
+    pub fn minus(&self, part: &Bundle) -> Result<Bundle> {
+        let mut out = self.clone();
+        for (id, &n) in &part.items {
+            let e = out.items.entry(id.clone()).or_insert(0);
+            *e = e.checked_sub(n).ok_or_else(|| error(codes::INSUFFICIENT, format!("not {n} {id}")))?;
+        }
+        for (id, &n) in &part.currency {
+            let e = out.currency.entry(id.clone()).or_insert(0);
+            if *e < n {
+                return Err(error(codes::INSUFFICIENT, format!("not {n} {id}")));
+            }
+            *e -= n;
+        }
+        Ok(out.trimmed())
+    }
+
+    /// `n` of it.
+    pub fn times(&self, n: u64) -> Result<Bundle> {
+        let k = i64::try_from(n).map_err(|_| error(codes::LIMIT, "too many"))?;
+        let mut out = Bundle::default();
+        for (id, &c) in &self.items {
+            out.items.insert(id.clone(), c.checked_mul(n).ok_or_else(|| error(codes::LIMIT, "too many"))?);
+        }
+        for (id, &c) in &self.currency {
+            out.currency.insert(id.clone(), c.checked_mul(k).ok_or_else(|| error(codes::LIMIT, "too much"))?);
+        }
+        Ok(out.trimmed())
+    }
+
+    /// Without its zero entries.
+    pub fn trimmed(mut self) -> Bundle {
+        self.items.retain(|_, n| *n > 0);
+        self.currency.retain(|_, n| *n != 0);
+        self
+    }
+}
+
+/// A player's inventory and wallet, and their mail: items given to them that did not fit,
+/// kept until they make room ([`Holdings::take_mail`]).
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq, Eq)]
+#[serde(default)]
+pub struct Holdings {
+    pub inventory: Inventory,
+    pub wallet: Wallet,
+    pub mail: BTreeMap<String, u64>,
+}
+
+impl Holdings {
+    pub fn new(slots: u32) -> Self {
+        Self { inventory: Inventory::new(slots), ..Self::default() }
+    }
+
+    /// Whether `b` could be taken.
+    pub fn has(&self, b: &Bundle) -> bool {
+        b.items.iter().all(|(id, &n)| self.inventory.count(id) >= n) && b.currency.iter().all(|(id, &n)| self.wallet.balance(id) >= n)
+    }
+
+    /// Takes `b`, or nothing: `insufficient`.
+    pub fn take(&mut self, b: &Bundle) -> Result<()> {
+        b.check()?;
+        if !self.has(b) {
+            return Err(error(codes::INSUFFICIENT, "not enough"));
+        }
+        for (id, &n) in &b.items {
+            self.inventory.remove(id, n)?;
+        }
+        for (id, &n) in &b.currency {
+            self.wallet.debit(id, n)?;
+        }
+        Ok(())
+    }
+
+    /// Gives `b`, or nothing: `full` when its items do not fit, `not_found` for an item the
+    /// catalog lacks.
+    pub fn give(&mut self, catalog: &Catalog, b: &Bundle) -> Result<()> {
+        b.check()?;
+        let mut next = self.clone();
+        for (id, &n) in &b.items {
+            next.inventory.add(catalog, id, n)?;
+        }
+        for (id, &n) in &b.currency {
+            next.wallet.credit(id, n)?;
+        }
+        *self = next;
+        Ok(())
+    }
+
+    /// Gives `b`, its items as far as they fit and the rest to the mail. It fails only for a
+    /// bundle the economy does not take: what another hub delivers always arrives.
+    pub fn give_or_mail(&mut self, catalog: &Catalog, b: &Bundle) -> Result<()> {
+        b.check()?;
+        for id in b.items.keys() {
+            catalog.item(id)?;
+        }
+        let mut next = self.clone();
+        for (id, &n) in &b.currency {
+            next.wallet.credit(id, n)?;
+        }
+        for (id, &n) in &b.items {
+            let left = next.inventory.add_what_fits(catalog, id, n);
+            if left > 0 {
+                *next.mail.entry(id.clone()).or_insert(0) += left;
+            }
+        }
+        *self = next;
+        Ok(())
+    }
+
+    /// Takes `pay` and gives `get` together, or neither.
+    pub fn swap(&mut self, catalog: &Catalog, pay: &Bundle, get: &Bundle) -> Result<()> {
+        let mut next = self.clone();
+        next.take(pay)?;
+        next.give(catalog, get)?;
+        *self = next;
+        Ok(())
+    }
+
+    /// Moves what fits from the mail into the inventory; answers what moved.
+    pub fn take_mail(&mut self, catalog: &Catalog) -> Bundle {
+        let mut moved = Bundle::default();
+        let mail = std::mem::take(&mut self.mail);
+        for (id, n) in mail {
+            let left = self.inventory.add_what_fits(catalog, &id, n);
+            if n > left {
+                moved.items.insert(id.clone(), n - left);
+            }
+            if left > 0 {
+                self.mail.insert(id, left);
+            }
+        }
+        moved
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::kit::econ::items::ItemDef;
+
+    fn catalog() -> Catalog {
+        Catalog::from(vec![ItemDef { id: "ore".into(), max_stack: 10, tradable: true, name: String::new() }])
+    }
+
+    #[test]
+    fn a_swap_is_all_or_nothing() {
+        let c = catalog();
+        let mut h = Holdings::new(1);
+        h.give(&c, &Bundle::coins("gold", 50)).unwrap();
+        let before = h.clone();
+        assert!(h.swap(&c, &Bundle::coins("gold", 20), &Bundle::item("ore", 11)).is_err(), "11 ore do not fit one slot");
+        assert_eq!(h, before);
+        h.swap(&c, &Bundle::coins("gold", 20), &Bundle::item("ore", 10)).unwrap();
+        assert_eq!((h.wallet.balance("gold"), h.inventory.count("ore")), (30, 10));
+    }
+
+    #[test]
+    fn what_does_not_fit_waits_in_the_mail() {
+        let c = catalog();
+        let mut h = Holdings::new(1);
+        h.give_or_mail(&c, &Bundle::item("ore", 14).plus(&Bundle::coins("gold", 3)).unwrap()).unwrap();
+        assert_eq!((h.inventory.count("ore"), h.mail["ore"], h.wallet.balance("gold")), (10, 4, 3));
+        h.take(&Bundle::item("ore", 6)).unwrap();
+        assert_eq!(h.take_mail(&c), Bundle::item("ore", 4));
+        assert!(h.mail.is_empty());
+    }
+
+    #[test]
+    fn bundles_add_take_and_multiply_without_overflow() {
+        let price = Bundle::coins("gold", 7);
+        assert_eq!(price.times(3).unwrap(), Bundle::coins("gold", 21));
+        assert!(price.times(u64::MAX).is_err());
+        let both = price.plus(&Bundle::item("ore", 2)).unwrap();
+        assert_eq!(both.minus(&Bundle::item("ore", 2)).unwrap(), price);
+        assert!(both.minus(&Bundle::coins("gold", 8)).is_err());
+        assert!(Bundle::coins("gold", -1).check().is_err());
+    }
+}

package/crates/ckx-sdk/src/kit/econ/holds.rs

@@ -0,0 +1,202 @@
+//! Escrow in the owner's own hub, and the references a hub answers once.
+//!
+//! A transfer between two players' hubs never leaves goods in neither or both: whatever drives
+//! it (a market) first [`Holds::hold`]s them in the giver's hub under a reference, later
+//! [`Holds::settle`]s the hold (the goods leave for good) and delivers them to the taker, or
+//! [`Holds::release`]s it back. Every step another hub asks for carries a reference of its own,
+//! which [`Applied`] answers once, so the driver retries a step until it gets an answer.
+//!
+//! A reference names one change, for as long as [`Applied`] keeps its answer: a driver never
+//! sends it for another, or the other is answered as the first was without running. So a driver
+//! makes references from its own key and counters, never from what a client sent (an `action_id`
+//! is the client's to reuse), and remembers which reference a client's resend should ask again.
+
+use std::collections::{BTreeMap, VecDeque};
+
+use serde::{Deserialize, Serialize};
+
+use super::check_reference;
+use super::holdings::{Bundle, Holdings};
+use super::items::Catalog;
+use crate::kit::{codes, error, error_code};
+use crate::{Error, Result};
+
+/// Goods held under references, out of their owner's holdings until settled or released.
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq, Eq)]
+#[serde(default)]
+pub struct Holds {
+    pub held: BTreeMap<String, Bundle>,
+}
+
+impl Holds {
+    /// Moves `bundle` out of `holdings` into a hold under `reference`. The same reference with
+    /// the same bundle again is the hold already made; with another, `conflict`.
+    pub fn hold(&mut self, holdings: &mut Holdings, reference: &str, bundle: &Bundle) -> Result<()> {
+        check_reference(reference)?;
+        bundle.check()?;
+        if let Some(held) = self.held.get(reference) {
+            return if held == bundle { Ok(()) } else { Err(error(codes::CONFLICT, format!("`{reference}` holds something else"))) };
+        }
+        holdings.take(bundle)?;
+        self.held.insert(reference.to_owned(), bundle.clone().trimmed());
+        Ok(())
+    }
+
+    /// Takes `part` out of the hold for good; the rest stays held, and an emptied hold is gone.
+    /// `not_found` for a reference not held, `insufficient` when it holds less.
+    pub fn settle(&mut self, reference: &str, part: &Bundle) -> Result<()> {
+        let held = self.held.get(reference).ok_or_else(|| error(codes::NOT_FOUND, format!("nothing is held as `{reference}`")))?;
+        let rest = held.minus(part)?;
+        if rest.is_empty() {
+            self.held.remove(reference);
+        } else {
+            self.held.insert(reference.to_owned(), rest);
+        }
+        Ok(())
+    }
+
+    /// Gives what the hold still has back to its owner (items that do not fit go to the mail);
+    /// answers what came back, nothing for a reference not held.
+    pub fn release(&mut self, holdings: &mut Holdings, catalog: &Catalog, reference: &str) -> Result<Bundle> {
+        let Some(held) = self.held.remove(reference) else { return Ok(Bundle::default()) };
+        holdings.give_or_mail(catalog, &held)?;
+        Ok(held)
+    }
+
+    /// Everything held, together.
+    pub fn total(&self) -> Bundle {
+        self.held.values().fold(Bundle::default(), |acc, b| acc.plus(b).unwrap_or(acc))
+    }
+}
+
+/// How long a reference's answer is kept.
+pub const APPLIED_TTL_MS: u64 = 7 * 24 * 3_600_000;
+/// How many references' answers are kept.
+pub const APPLIED_MAX: usize = 4_096;
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
+struct Done {
+    reference: String,
+    at: u64,
+    ok: bool,
+    reply: Vec<u8>,
+}
+
+/// The answer each reference got, so a step asked for again is answered as it was the first
+/// time. Keep it in the hub's state. A refusal coded `unavailable` is not kept: it says the step
+/// did not run.
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq, Eq)]
+pub struct Applied {
+    #[serde(default)]
+    kept: VecDeque<Done>,
+}
+
+impl Applied {
+    pub fn replay(&self, reference: &str, now: u64) -> Option<Result<Vec<u8>>> {
+        let d = self.kept.iter().rev().find(|d| d.reference == reference && now.saturating_sub(d.at) < APPLIED_TTL_MS)?;
+        Some(if d.ok { Ok(d.reply.clone()) } else { Err(Error::new(String::from_utf8_lossy(&d.reply).into_owned())) })
+    }
+
+    pub fn record(&mut self, reference: &str, result: &Result<Vec<u8>>, now: u64) {
+        if let Err(e) = result
+            && error_code(&e.0).is_some_and(|(c, _)| c == codes::UNAVAILABLE)
+        {
+            return;
+        }
+        while self.kept.front().is_some_and(|d| now.saturating_sub(d.at) >= APPLIED_TTL_MS) || self.kept.len() >= APPLIED_MAX {
+            self.kept.pop_front();
+        }
+        let (ok, reply) = match result {
+            Ok(r) => (true, r.clone()),
+            Err(e) => (false, e.0.clone().into_bytes()),
+        };
+        self.kept.push_back(Done { reference: reference.to_owned(), at: now, ok, reply });
+    }
+
+    /// Runs `act` once per `reference`: asked again, it answers what it answered first.
+    pub fn run<H>(
+        hub: &mut H,
+        applied: fn(&mut H) -> &mut Applied,
+        reference: &str,
+        now: u64,
+        act: impl FnOnce(&mut H) -> Result<Vec<u8>>,
+    ) -> Result<Vec<u8>> {
+        check_reference(reference)?;
+        if let Some(answer) = applied(hub).replay(reference, now) {
+            return answer;
+        }
+        let result = act(hub);
+        applied(hub).record(reference, &result, now);
+        result
+    }
+
+    pub fn len(&self) -> usize {
+        self.kept.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.kept.is_empty()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::kit::econ::items::ItemDef;
+
+    fn setup() -> (Catalog, Holdings) {
+        let c = Catalog::from(vec![ItemDef { id: "ore".into(), max_stack: 10, tradable: true, name: String::new() }]);
+        let mut h = Holdings::new(2);
+        h.give(&c, &Bundle::item("ore", 8).plus(&Bundle::coins("gold", 40)).unwrap()).unwrap();
+        (c, h)
+    }
+
+    #[test]
+    fn a_hold_leaves_the_holdings_and_comes_back_on_release() {
+        let (c, mut h) = setup();
+        let mut holds = Holds::default();
+        holds.hold(&mut h, "o:1", &Bundle::coins("gold", 30)).unwrap();
+        holds.hold(&mut h, "o:1", &Bundle::coins("gold", 30)).unwrap();
+        assert_eq!(h.wallet.balance("gold"), 10, "the same hold twice is one hold");
+        assert!(holds.hold(&mut h, "o:1", &Bundle::coins("gold", 5)).is_err(), "a reference holds one thing");
+        assert!(holds.hold(&mut h, "o:2", &Bundle::coins("gold", 11)).is_err(), "not more than there is");
+        holds.settle("o:1", &Bundle::coins("gold", 12)).unwrap();
+        assert_eq!(holds.release(&mut h, &c, "o:1").unwrap(), Bundle::coins("gold", 18));
+        assert_eq!(h.wallet.balance("gold"), 28);
+        assert_eq!(holds.release(&mut h, &c, "o:1").unwrap(), Bundle::default(), "released once");
+        assert!(holds.settle("o:1", &Bundle::coins("gold", 1)).is_err());
+    }
+
+    #[test]
+    fn a_reference_is_longer_than_an_id_but_bounded() {
+        let (_, mut h) = setup();
+        let mut holds = Holds::default();
+        let long = "r".repeat(crate::kit::econ::REFERENCE_MAX);
+        holds.hold(&mut h, &long, &Bundle::coins("gold", 1)).unwrap();
+        assert!(holds.hold(&mut h, &format!("{long}r"), &Bundle::coins("gold", 1)).is_err());
+        let mut applied = Applied::default();
+        assert!(Applied::run(&mut applied, |a| a, &format!("{long}r"), 0, |_| Ok(vec![])).is_err());
+    }
+
+    #[test]
+    fn a_reference_is_answered_once_and_unavailable_is_not_an_answer() {
+        struct Hub {
+            applied: Applied,
+            runs: u32,
+        }
+        let mut hub = Hub { applied: Applied::default(), runs: 0 };
+        let act = |h: &mut Hub| {
+            h.runs += 1;
+            Ok(vec![1])
+        };
+        assert_eq!(Applied::run(&mut hub, |h| &mut h.applied, "d:1", 0, act).unwrap(), vec![1]);
+        assert_eq!(Applied::run(&mut hub, |h| &mut h.applied, "d:1", 5, act).unwrap(), vec![1]);
+        assert_eq!(hub.runs, 1);
+        let mut applied = Applied::default();
+        applied.record("d:2", &Err(error(codes::UNAVAILABLE, "the market did not answer")), 0);
+        assert!(applied.replay("d:2", 1).is_none());
+        applied.record("d:3", &Err(error(codes::INSUFFICIENT, "no")), 0);
+        assert!(applied.replay("d:3", 1).unwrap().is_err());
+        assert!(applied.replay("d:3", APPLIED_TTL_MS).is_none(), "kept for a week");
+    }
+}

package/crates/ckx-sdk/src/kit/econ/items.rs

@@ -0,0 +1,212 @@
+//! Items: what a game's items are ([`Catalog`]), and an inventory of stacks with a number of
+//! slots ([`Inventory`]).
+
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+use crate::Result;
+use crate::kit::{codes, error};
+
+fn one() -> u64 {
+    1
+}
+
+fn yes() -> bool {
+    true
+}
+
+/// One kind of item.
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
+pub struct ItemDef {
+    pub id: String,
+    /// What one slot holds; 1 for an item that does not stack.
+    #[serde(default = "one")]
+    pub max_stack: u64,
+    /// Whether it may change hands (a market's order book, a trade).
+    #[serde(default = "yes")]
+    pub tradable: bool,
+    #[serde(default)]
+    pub name: String,
+}
+
+/// The game's items, by id.
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq, Eq)]
+#[serde(from = "Vec<ItemDef>", into = "Vec<ItemDef>")]
+pub struct Catalog {
+    items: BTreeMap<String, ItemDef>,
+}
+
+impl From<Vec<ItemDef>> for Catalog {
+    fn from(items: Vec<ItemDef>) -> Self {
+        Self { items: items.into_iter().map(|i| (i.id.clone(), i)).collect() }
+    }
+}
+
+impl From<Catalog> for Vec<ItemDef> {
+    fn from(c: Catalog) -> Self {
+        c.items.into_values().collect()
+    }
+}
+
+impl Catalog {
+    pub fn get(&self, id: &str) -> Option<&ItemDef> {
+        self.items.get(id)
+    }
+
+    /// The item, or `not_found`.
+    pub fn item(&self, id: &str) -> Result<&ItemDef> {
+        self.items.get(id).ok_or_else(|| error(codes::NOT_FOUND, format!("there is no item `{id}`")))
+    }
+
+    pub fn len(&self) -> usize {
+        self.items.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.items.is_empty()
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = &ItemDef> {
+        self.items.values()
+    }
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq)]
+pub struct Stack {
+    pub item: String,
+    pub count: u64,
+}
+
+/// Stacks of items in a number of slots. Adding fills the item's stacks before starting new
+/// ones; a stack holds at most its item's `max_stack`.
+#[derive(Serialize, Deserialize, Clone, Debug, Default, PartialEq, Eq)]
+pub struct Inventory {
+    pub slots: u32,
+    pub stacks: Vec<Stack>,
+}
+
+impl Inventory {
+    pub fn new(slots: u32) -> Self {
+        Self { slots, stacks: Vec::new() }
+    }
+
+    pub fn count(&self, item: &str) -> u64 {
+        self.stacks.iter().filter(|s| s.item == item).map(|s| s.count).sum()
+    }
+
+    /// How many of `item` still fit.
+    pub fn room(&self, catalog: &Catalog, item: &str) -> u64 {
+        let Some(def) = catalog.get(item) else { return 0 };
+        let max = def.max_stack.max(1);
+        let in_stacks: u64 = self.stacks.iter().filter(|s| s.item == item).map(|s| max.saturating_sub(s.count)).sum();
+        let free = u64::from(self.slots).saturating_sub(self.stacks.len() as u64);
+        in_stacks.saturating_add(free.saturating_mul(max))
+    }
+
+    /// Adds `count` of `item`, or nothing: `not_found` for an item the catalog lacks, `full`
+    /// when they do not fit.
+    pub fn add(&mut self, catalog: &Catalog, item: &str, count: u64) -> Result<()> {
+        let max = catalog.item(item)?.max_stack.max(1);
+        if count > self.room(catalog, item) {
+            return Err(error(codes::FULL, format!("{count} {item} do not fit")));
+        }
+        let mut left = count;
+        for s in self.stacks.iter_mut().filter(|s| s.item == item) {
+            let put = left.min(max.saturating_sub(s.count));
+            s.count += put;
+            left -= put;
+        }
+        while left > 0 {
+            let put = left.min(max);
+            self.stacks.push(Stack { item: item.to_owned(), count: put });
+            left -= put;
+        }
+        Ok(())
+    }
+
+    /// Adds what fits; answers how many did not.
+    pub fn add_what_fits(&mut self, catalog: &Catalog, item: &str, count: u64) -> u64 {
+        let fits = count.min(self.room(catalog, item));
+        if fits > 0 && self.add(catalog, item, fits).is_err() {
+            return count;
+        }
+        count - fits
+    }
+
+    /// Removes `count` of `item`, from its last stacks first, or nothing: `insufficient`.
+    pub fn remove(&mut self, item: &str, count: u64) -> Result<()> {
+        if self.count(item) < count {
+            return Err(error(codes::INSUFFICIENT, format!("not {count} {item}")));
+        }
+        let mut left = count;
+        for s in self.stacks.iter_mut().rev().filter(|s| s.item == item) {
+            let take = left.min(s.count);
+            s.count -= take;
+            left -= take;
+            if left == 0 {
+                break;
+            }
+        }
+        self.stacks.retain(|s| s.count > 0);
+        Ok(())
+    }
+
+    /// Every item's total, by id.
+    pub fn totals(&self) -> BTreeMap<String, u64> {
+        let mut out = BTreeMap::new();
+        for s in &self.stacks {
+            *out.entry(s.item.clone()).or_insert(0) += s.count;
+        }
+        out
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn catalog() -> Catalog {
+        Catalog::from(vec![
+            ItemDef { id: "wood".into(), max_stack: 10, tradable: true, name: String::new() },
+            ItemDef { id: "sword".into(), max_stack: 1, tradable: true, name: String::new() },
+        ])
+    }
+
+    #[test]
+    fn stacks_fill_before_new_slots_and_a_full_inventory_takes_nothing() {
+        let c = catalog();
+        let mut inv = Inventory::new(2);
+        inv.add(&c, "wood", 7).unwrap();
+        inv.add(&c, "wood", 5).unwrap();
+        assert_eq!(inv.stacks.iter().map(|s| s.count).collect::<Vec<_>>(), vec![10, 2]);
+        assert_eq!(inv.room(&c, "wood"), 8);
+        assert_eq!(inv.room(&c, "sword"), 0, "both slots are taken");
+        let before = inv.clone();
+        assert!(inv.add(&c, "wood", 9).is_err());
+        assert_eq!(inv, before, "all or nothing");
+        assert_eq!(inv.add_what_fits(&c, "wood", 9), 1);
+        assert!(inv.add(&c, "stone", 1).is_err(), "not in the catalog");
+    }
+
+    #[test]
+    fn removing_takes_from_the_last_stacks_and_frees_their_slots() {
+        let c = catalog();
+        let mut inv = Inventory::new(3);
+        inv.add(&c, "wood", 14).unwrap();
+        inv.remove("wood", 6).unwrap();
+        assert_eq!(inv.stacks, vec![Stack { item: "wood".into(), count: 8 }]);
+        assert!(inv.remove("wood", 9).is_err());
+        assert_eq!(inv.count("wood"), 8);
+    }
+
+    #[test]
+    fn a_catalog_reads_and_writes_as_a_list() {
+        let json = r#"[{"id":"wood","max_stack":10},{"id":"sword"}]"#;
+        let c: Catalog = serde_json::from_str(json).unwrap();
+        assert_eq!(c.item("sword").unwrap().max_stack, 1);
+        assert!(c.item("wood").unwrap().tradable);
+        let back = serde_json::to_value(&c).unwrap();
+        assert_eq!(back.as_array().unwrap().len(), 2);
+    }
+}