docs(rust): the Economics spike and its design — D335, D336 (PLAN_REDESIGNS §11.2) #338

wtclaude · 2026-10-12T11:36:06Z

wtclaude commented

2026-10-12 11:36:06 +00:00

What & why

This is the first item of PLAN_REDESIGNS.md §11 (§9 item 7): the source pull and rig spike that §11.1 asks for before any Economics code, plus the two decisions the spike raised. It adds no code.

§11.2.1, the spike. Economics 3.9.2 was pulled from umod.org/plugins/Economics.cs on 2026-10-12. A throwaway plugin called its API and logged its hooks on both rigs (Rust 25877464, Oxide 2.0.7826, Carbon 2.0.262), and both frameworks answered identically. What it found that the design depends on:

An account Economics has never seen reads as the starting balance, 1000 by default. Nothing is stored for it.
Deposit returns true while adding less than asked, because of rounding and the balance limit. What was paid has to be measured as the balance after less the balance before.
Withdraw is all or nothing.
An amount passed as an int matches no overload, and nothing happens. Amounts must be boxed as double.
String ids are not validated.
OnEconomicsDataWiped is raised in two shapes, and one (IPlayer) method binds both.
500 balance reads take about 2.7 ms.

Decisions (org lead, 2026-10-12):

D335: coins paid by an event are kept. Core reverts a ledgered step on every terminal path, a normal finish included, so §11.2's "ledgered, withdrawn on revert" would take a prize back. rust.coins.pay is reversible: 'none', like Module-uo's uo.item.grant.
D336: the richest column and Magnate rank only balances above the starting balance. The balance is read when a player connects and whenever it changes.

§11.2.2, the design to build. Everything below is on protocol 14:

hello's integrations.economics;
economics.pay (key-remembered, never pays twice, an optional in-game message);
economics.balances;
economics.adjust for staff;
player.tally.balance, sent as a value;
the economics.wiped event;
three sidecar forwards;
the step, the balance column, the account and admin pages, and the app's account screen.

The installer and the egg are untouched (D199). §11.2.3 lists the walk rows for the end-of-plan walk (D331). §7's protocol table gains the three rows.

How it was tested

Docs only.
The spike's console output from both rigs is summarised in §11.2.1.
Both rigs were cleaned afterwards: the spike plugin, Economics, and its data and config are gone.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

No AI tools were used to produce this contribution.
AI tools were used. Tool(s): Claude Code (Claude Opus 5.5). I have reviewed and understand
every change, and take responsibility for it. AI-authored commits are
marked with a Co-Authored-By / Assisted-By trailer.

License

I agree that my contribution is licensed under this project's license
(GNU GPL v3.0 or later), and I have the right to contribute it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY

## What & why This is the first item of `PLAN_REDESIGNS.md` §11 (§9 item 7): the source pull and rig spike that §11.1 asks for before any Economics code, plus the two decisions the spike raised. It adds no code. **§11.2.1, the spike.** Economics 3.9.2 was pulled from `umod.org/plugins/Economics.cs` on 2026-10-12. A throwaway plugin called its API and logged its hooks on both rigs (Rust 25877464, Oxide 2.0.7826, Carbon 2.0.262), and **both frameworks answered identically**. What it found that the design depends on: - An account Economics has never seen reads as the starting balance, 1000 by default. Nothing is stored for it. - `Deposit` returns `true` while adding less than asked, because of rounding and the balance limit. What was paid has to be measured as the balance after less the balance before. - `Withdraw` is all or nothing. - An amount passed as an `int` matches no overload, and nothing happens. Amounts must be boxed as `double`. - String ids are not validated. - `OnEconomicsDataWiped` is raised in two shapes, and one `(IPlayer)` method binds both. - 500 balance reads take about 2.7 ms. **Decisions (org lead, 2026-10-12):** - **D335: coins paid by an event are kept.** Core reverts a ledgered step on every terminal path, a normal finish included, so §11.2's "ledgered, withdrawn on revert" would take a prize back. `rust.coins.pay` is `reversible: 'none'`, like Module-uo's `uo.item.grant`. - **D336: the richest column and *Magnate* rank only balances above the starting balance.** The balance is read when a player connects and whenever it changes. **§11.2.2, the design to build.** Everything below is on protocol 14: - hello's `integrations.economics`; - `economics.pay` (key-remembered, never pays twice, an optional in-game message); - `economics.balances`; - `economics.adjust` for staff; - `player.tally.balance`, sent as a value; - the `economics.wiped` event; - three sidecar forwards; - the step, the balance column, the account and admin pages, and the app's account screen. The installer and the egg are untouched (D199). §11.2.3 lists the walk rows for the end-of-plan walk (D331). §7's protocol table gains the three rows. ## How it was tested - Docs only. - The spike's console output from both rigs is summarised in §11.2.1. - Both rigs were cleaned afterwards: the spike plugin, Economics, and its data and config are gone. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [ ] No AI tools were used to produce this contribution. - [x] AI tools were used. Tool(s): `Claude Code (Claude Opus 5.5)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` / `Assisted-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY

wtclaude added 1 commit 2026-10-12 11:36:09 +00:00

docs(rust): the Economics spike and its design — D335, D336 (PLAN_REDESIGNS §11.2) 168208d21c

§11's first item. Economics 3.9.2 was pulled from uMod and spiked on
both rigs (Rust 25877464, Oxide 2.0.7826, Carbon 2.0.262); both
frameworks answered identically. §11.2.1 records the API and hooks as
found: an unseen account reads as the starting balance, a deposit can
report true while adding less, withdraw is all or nothing, and an
amount must be a double.

Two decisions from the org lead: coins paid by an event are kept
(D335; core reverts a ledgered step on every terminal path, a normal
finish included), and the richest column ranks only balances above
the starting balance (D336). §11.2.2 is the design to build on
protocol 14; §11.2.3 joins the end-of-plan walk.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E14m6SuuY6i1vASFeGDBeY

whitlocktech merged commit 0f4d99c9fa into main

2026-10-12 11:41:47 +00:00

whitlocktech deleted branch docs/rust-economics-decisions

2026-10-12 11:41:47 +00:00

whitlocktech referenced this issue from a commit

2026-10-12 11:41:48 +00:00

Merge pull request 'docs(rust): the Economics spike and its design — D335, D336 (PLAN_REDESIGNS §11.2)' (#338) from docs/rust-economics-decisions into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: RunicGateway/docs#338