Currencies, vendors, trade, mail and the auction

An EconomyIntent is a set of movements that either all happen or none do, named by a key that makes replaying it free. A Currency is gold, tokens, marks or karma — one type with a cap, a decay and conversions. A VendorState is one vendor's stock, restock clock and buyback window. A TradeSession is two players swapping, with the confirm-lock that makes the last-moment swap impossible. A PostOffice delivers goods and money to people who are not online, which is what an AuctionHouse settles into, and an IMarketModel says what one of something goes for.

The part of a game where correctness is not negotiable. Doc 28: *"every one of those is a ledger transaction with an idempotency key"* — a duplicated settlement, a retried claim and a confirmation that arrives twice are all no-ops the second time by construction.

Compile an EconomyLibrary, give the realm an IEconomyLedger, and post intents.

⚠ This library never holds or moves anything. It says what must move; the realm applies it. That is what keeps a trade escrow from being a second container implementation, and it is the same shape QuestJournal.TurnIn has.

⚠ Balanced per asset, not overall — otherwise gold leaving one account can be paid for by ore arriving in another.

⚠ A player may not go negative; a world account may. That asymmetry is what makes a world account a source or a sink.

⚠ A confirmation quotes the revision it saw. "Any change re-opens both confirmations" loses the race where a change and a confirmation cross in flight; the revision turns that into a refusal.

⚠ Stock is taken only after the ledger says yes, and buyback costs exactly what was paid.

⚠ A cap reports its overflow and a conversion keeps its remainder; decay rounds down so it can reach zero.

⚠ Everything is escrowed when it is offered, not when it is taken. Mail escrows an attachment on posting and an auction escrows the goods on listing; recording a promise and moving it on claim lets a sender attach a sword, post it, sell it, and have the recipient claim a second one.

⚠ Outbidding refunds the previous bidder in the same intent, because two operations is a window in which the refund fails and somebody's gold is gone. ⚠ The deposit comes back on a sale and is destroyed on an expiry, which is what prices listing something nobody wants. ⚠ A listing with a bid may not be withdrawn, or a seller cancels every auction they are about to lose.

A MemoryEconomyLedger remembers every key it has applied, and by default it remembers them for ever — which over a week of uptime is every key of that week. Give it a KeyHorizon and sweep it off the frame path:

⚠ The argument is the retry window, not the horizon, and that is the whole of the type. The two failure modes are not comparable: too long costs memory, which is visible in a graph and recoverable by restarting; too short duplicates an item, which is invisible, permanent and indistinguishable from an exploit when a player reports it. So Outliving is the only bounded constructor, its Guaranteed retention is always strictly longer than the window it was built from, and a horizon shorter than the retries it must outlive cannot be written down.

⚠ Which is why the default is the leak. There is no default horizon, because a number nobody chose is not safer than an unbounded set — it is the same risk with the evidence removed.

⚠ And a departing player's rows are the realm's to take away. Release hands everything an account holds to the world account it was seeded out of and drops the rows. It is deliberately not an intent: nothing has moved, the player still owns what they left with, and writing a movement would put a handover in the journal as a transaction.

Two currencies and a vendor:

Buying something:

A trade, from the server's side:

Minting and sinking, which is what a world account is for:

Selling something, and what the fee destroys:

• Items — what a vendor's stock names.
• Inventory — what actually moves the goods this library reports.
• Requirements — what gates a stock row.