💰 Economy System — System Guarantees Matrix

This page defines the behavioural contract of the Economy system.

No marketing. No implication. Just guarantees — and explicit non-guarantees.

---

🔎 Quick Navigation

• 1. Composition & Dependency
• 1. Value Ledger
• 1. Item Store
• 1. Shop Service
• 1. Crafting Service
• 1. Reward Service
• 1. Bootstrap
• 1. Models & Results
• 1. Telemetry
• 1. Diagnostics Surface
• Non-Guarantees
• Final Summary

---

1. Composition & Dependency

Economy overall

Aspect	Guarantee
Depends on Currency	❌ No
Can replace money implementation	✔ Via IValueLedger
Can replace item implementation	✔ Via IItemStore
Owns ledger truth	❌ No
Owns inventory truth	❌ No
Orchestrates gameplay transactions	✔ Yes

Dependency boundary

Layer	Responsibility
Currency	Money truth, policy, authority, escrow, audit, batching
Economy	Shop / crafting / reward sequencing and rollback orchestration
Item store	Item ownership, add/remove rules, capacity

---

2. Value Ledger

IValueLedger

Aspect	Guarantee
CanPay	Best-effort UX preflight only
Pay / Grant	✔ Authoritative mutations
sourceId propagation	✔ Currency ops propagate it when supported
Hard atomicity across multi-line money bundles	❌ Not guaranteed
Rollback on partial money failure	✔ Best-effort
Policy participation	✔ Yes, when supported by implementation
Escrow usage	✔ When supported by implementation

Built-in CurrencyValueLedger

Aspect	Guarantee
Money preflight and Pay alignment	✔ Uses same effective-debit policy computation path
Escrow-first path	✔ When escrow capability exists
Direct debit fallback	✔ When escrow is unavailable and policy does not require it
Batch event emission	✔ Uses Currency batching wrapper when available
Rollback of direct debits	✔ Best-effort via compensating credits
Telemetry reason normalization	✔ Uses canonical reasons in built-in implementation

---

3. Item Store

IItemStore

Aspect	Guarantee
HasSpaceFor / CanRemove	Best-effort UX preflight only
Add / Remove	✔ Authoritative item mutations
sourceId propagation	❌ Not supported on item operations
Capacity / ownership enforcement	✔ By store implementation
Store implementation interchangeable	✔ Yes

Built-in Inventory-backed store

Aspect	Guarantee
Requires Inventory package	✔ REV_INVENTORY_PRESENT
Uses named container	✔ Yes
GUID → definition resolver required for adds	✔ Yes
Missing resolver / unknown GUID	✔ Returns ResolverMissing
Missing container	✔ Returns ContainerMissing
Debug handle exposed	✔ Via IItemStoreDebug for diagnostics only
Gameplay support for debug handle	❌ Not supported

---

Scope note:
The following sections describe the built-in Economy service implementations.
Custom implementations of the public abstractions may behave differently.

---

4. Shop Service

Built-in ShopService.Buy

Aspect	Guarantee
Execution order	✔ Money → item costs → deliveries
Currency-only buys without store	✔ Supported
Item-based buy without store	✔ Fails with ServiceMissing
Preflight checks	✔ Money, item ownership, delivery space
Rollback on item-cost failure	✔ Refunds money; best-effort rollback of prior item removals
Rollback on delivery failure	✔ Best-effort undo of delivered items, removed item costs, and money refund
Hard atomicity	❌ Not guaranteed
Uses caller-facing abstractions only	✔ Yes (IValueLedger, IItemStore)

Built-in ShopService.Sell

Aspect	Guarantee
Execution order	✔ Remove items first → grant payout
Requires store	✔ Yes
Requires payout money lines	✔ Yes in built-in implementation
Rollback on payout failure	✔ Best-effort re-add of removed items
Hard atomicity	❌ Not guaranteed

---

5. Crafting Service

Built-in CraftingService

Aspect	Guarantee
Execution order	✔ Pay money → remove ingredients → add result
Requires ledger	✔ Yes
Requires store	✔ Yes
Requires valid result item	✔ Yes
Ingredient ownership preflight	✔ Yes
Result space preflight	✔ Yes
Rollback on ingredient removal failure	✔ Refunds money when already paid
Rollback on result-add failure	✔ Best-effort re-add of removed ingredients and money refund
Hard atomicity	❌ Not guaranteed
Telemetry	Currency ops propagate sourceId; item ops do not

---

6. Reward Service

Built-in RewardService

Aspect	Guarantee
Execution order	✔ Money first → items second
Store required for item rewards	✔ Yes
Preflight item space checks	✔ Yes in built-in implementation
Money rollback if item add fails	❌ No, by design
Hard atomicity	❌ Not guaranteed
Partial-success possibility	✔ Yes when money succeeds and item stage fails
Telemetry	Currency ops propagate sourceId; item ops do not

---

7. Bootstrap

EconomyBootstrap

Aspect	Guarantee
Returns abstractions only	✔ Yes
Exposes concrete implementations	❌ No
Required for using Economy	❌ No
Convenience composition helper	✔ Yes
Currency-only build supported	✔ Yes
Inventory-enabled build supported	✔ Yes, when Inventory package is present
store null in currency-only build	✔ Yes
Public contract includes concrete types	❌ No

---

8. Models & Results

EcoOpResult

Aspect	Guarantee
Explicit success flag	✔ Yes
Machine-readable code	✔ Yes
Optional message	✔ Yes
Implicit bool conversion	❌ Not supported
Equality support	✔ Yes
Comparer-by-code available	✔ Via EcoOpResultComparers.ByCode

EcoOpCode

Aspect	Guarantee
Public operation outcome set	✔ Yes
Branch-safe for gameplay/UI	✔ Yes
Covers item + money failure categories	✔ Yes

PriceBundle, ChargeLine, ItemLine

Aspect	Guarantee
Public value types	✔ Yes
Money ids normalized in ChargeLine	✔ Lowercase/trimmed on construction
Item GUID trimmed in ItemLine	✔ Yes
Construction validates values	❌ No; callers should check IsValid
Bundle clones provided lists	❌ No

LedgerPreflightMode

Aspect	Guarantee
Affects CanPay UX semantics	✔ Yes
Changes authoritative debit behaviour	❌ No

---

9. Telemetry

EcoReasons

Aspect	Guarantee
Public canonical reason constants	✔ Yes
Helps prevent telemetry drift when used consistently	✔ Yes
Required for API correctness	❌ No

EcoSource

Aspect	Guarantee
Canonical sourceId format builder	✔ Yes
Request prefix normalization (rid:)	✔ Yes
Delimiter sanitization	✔ Yes
Bounded part lengths	✔ Yes

Propagation rules

Aspect	Guarantee
Currency operations	✔ sourceId passed when supported by underlying currency
Item operations	❌ No sourceId propagation

---

10. Diagnostics Surface

IItemStoreDebug

Aspect	Guarantee
Public visibility	✔ Yes
Intended for diagnostics/tooling only	✔ Yes
Supported gameplay dependency	❌ No
Opaque handle contract	✔ Yes
Stable underlying handle type	❌ Not guaranteed

---

Non-Guarantees

Economy does not guarantee:

• ❌ Independence from Currency when using the built-in Currency-backed stack
• ❌ Hard transactional atomicity across money + item flows
• ❌ Perfect rollback under arbitrary underlying service failures
• ❌ Networking / replication / prediction
• ❌ Server authority implementation
• ❌ sourceId propagation on item operations
• ❌ Automatic inventory support without an IItemStore
• ❌ Automatic escrow composition just because Currency policy requires it
• ❌ Stable concrete built-in implementation types
• ❌ Debug-handle stability for gameplay use

---

Final Summary

Layer	Strong Guarantee	Best Effort	Not Guaranteed
Public abstractions	✔
Built-in composition via bootstrap	✔
Money orchestration through ledger	✔
Item orchestration through store	✔
Multi-step rollback		✔
Hard atomicity across mixed resources			❌
Money rollback in reward flows			❌
Concrete implementation stability			❌

---

System Philosophy

Economy is:

• explicit
• orchestrated
• abstraction-first
• honest about rollback limits

It is not:

• a ledger
• an inventory system
• a networking layer
• an ACID transaction engine