Skip to content

🧪 RevFramework Economy — Testing Philosophy

This document explains how the Economy system is tested, what the tests are designed to protect, and what they intentionally do not claim.

This is not marketing material.

It is an engineering-facing overview of the testing philosophy behind the Economy system.

🎯 The Goal of the Tests

The Economy tests exist to protect:

  • behavioural guarantees
  • regression safety
  • deterministic framework behaviour
  • explicit transaction semantics
  • edge-case handling
  • compensation and rollback expectations
  • public integration safety

The tests are designed to answer questions like:

  • “Does this behaviour still work after refactors?”
  • “Did a hidden ordering assumption accidentally change?”
  • “Will this failure path still compensate correctly?”
  • “Does currency/item integration still fail safely?”
  • “Are partial-mutation behaviours still honest and documented?”
  • “Do public seams behave predictably when consumers use them badly?”

The goal is predictability, not “perfect software.”

🔒 Hostile Consumer Tests

A large part of the Economy suite is written as Hostile Consumer tests.

This means the tests interact with the system the way a real project would:

  • through public APIs
  • through supported abstractions
  • through supported service interfaces
  • through documented bootstrap/facade entry points
  • without reflection
  • without private-field access
  • without editor hacks

These tests intentionally avoid depending on implementation details.

If a Hostile test passes, the supported public Economy contract is behaving correctly.

Hostile tests cover both:

  • bad consumer input
  • normal happy-path public usage

That matters because a system should not only survive abuse — it should also prove that regular public use works as expected.

⚙️ InternalTruth Tests

The Economy system also contains InternalTruth tests.

These tests validate internal framework assumptions that are important for long-term stability but are not part of the supported public API.

Examples include:

  • service execution ordering
  • rollback ordering
  • compensation sequencing
  • currency-to-economy result mapping
  • price bundle normalization
  • policy-adjusted debit computation
  • escrow hold / commit / release behaviour
  • canonical reason/source propagation

InternalTruth tests are intentionally separated from Hostile tests.

They exist to protect framework integrity during future refactors.

They are not extension guidance.

They do not make internals part of the supported user-facing API.

🧩 What the Economy Tests Validate

The current Economy test suite validates behaviour including:

Public Model & Result Semantics

  • ChargeLine normalization
  • ItemLine validation
  • PriceBundle behaviour
  • EcoOpResult success/failure semantics
  • equality and comparer behaviour
  • string/debug output expectations
  • canonical source id formatting

Public Service Contracts

  • IValueLedger
  • IItemStore
  • IShopService
  • IRewardService
  • ICraftingService

The tests verify that these interfaces can be implemented by consumers and that public calls fail safely when dependencies are missing or invalid.

Bootstrap / Facade Behaviour

  • currency-only Economy bootstrap
  • service creation
  • null-store behaviour for currency-only composition
  • safe failure for missing player or currency service
  • public service access through supported facades

Hostile Input Handling

  • invalid money lines
  • invalid item lines
  • null owners
  • missing ledgers
  • missing item stores
  • missing sell items
  • unsupported item operations in currency-only mode
  • invalid result items
  • no mutation when validation fails

Happy Path Behaviour

  • currency-only buys
  • money rewards
  • item rewards
  • shop buys with money and item delivery
  • shop buys with item-price costs
  • shop sells
  • crafting with money costs
  • crafting with item costs
  • crafting with mixed money and item costs

These tests prove that supported public flows work before internal implementation details are tested.

Preflight vs Authority

Economy explicitly treats preflight as advisory.

The tests validate that:

  • CanPay is not authoritative
  • HasSpaceFor is not authoritative
  • CanRemove is not authoritative
  • execution methods remain the source of truth
  • late authoritative failures are handled safely

This protects the framework’s core rule:

Preflight helps UX.
Operation results decide truth.

Shop Behaviour

The Shop tests validate:

  • money-only purchases
  • item-price purchases
  • item delivery
  • missing-store semantics
  • buy ordering: money → item costs → delivery
  • delivery failure compensation
  • item-cost rollback
  • money refund behaviour
  • sell ordering: remove items → grant payout
  • sold-item restoration when payout fails
  • source id generation from vendor/request ids

Reward Behaviour

The Reward tests validate:

  • money-only rewards
  • item-only rewards
  • mixed money and item rewards
  • item preflight before item grants
  • all item rewards being preflighted before mutation
  • no item add when preflight fails
  • ledger reason/source forwarding
  • intentionally non-transactional money behaviour

Important truth:

If a reward grants currency and a later item grant fails, the currency is not automatically rolled back.

That behaviour is deliberate and documented.

Crafting Behaviour

The Economy crafting tests validate:

  • service dependency checks
  • result validation
  • money preflight
  • ingredient preflight
  • result-space preflight
  • execution ordering: money debit → ingredient remove → result add
  • money refund when ingredient removal fails after payment
  • ingredient restoration when result delivery fails
  • mixed money + item cost behaviour
  • reason and source forwarding to money operations

This protects the Economy-level craft transaction semantics.

Ledger Behaviour

The ledger tests validate:

  • CanPay behaviour
  • duplicate money-line normalization
  • balance checks
  • pay/debit behaviour
  • grant/credit behaviour
  • no-money bundles returning OK
  • overflow handling
  • direct debit rollback
  • direct grant rollback
  • honest partial mutation when rollback itself fails
  • canonical reason/source propagation
  • default reason fallback

Policy & Preflight Modes

The policy tests validate:

  • strict preflight mode
  • policy-approved preflight mode
  • policy-adjusted effective debits
  • zero or negative effective debits being skipped
  • policy failure mapping to Economy result codes

This protects the distinction between:

  • nominal price
  • policy-adjusted effective debit
  • preflight behaviour
  • authoritative payment behaviour

Escrow Path

The escrow-specific tests validate:

  • RequireEscrow failure when no escrow provider exists
  • hold behaviour
  • commit behaviour
  • release behaviour
  • hold failure cleanup
  • commit failure cleanup
  • partial mutation truth when a later commit fails after an earlier commit succeeded

The tests do not pretend escrow makes every multi-line transaction magically atomic.

They validate the actual staged behaviour.

Rollback & Compensation Helpers

The compensation tests validate:

  • added-item rollback removes items in reverse order
  • removed-item rollback restores items in reverse order
  • count-limited rollback only affects the intended prefix
  • null and zero-count rollback paths are safe
  • failed rollbacks do not crash the compensation path

This protects the shared rollback utilities used by the built-in Economy services.

🧠 Deterministic Test Infrastructure

The Economy tests use deterministic fake services and stores including:

  • fake currency services
  • spy currency services
  • hostile item stores
  • recording stores
  • policy-aware currency fakes
  • escrow-capable currency fakes
  • ledger spies

These fakes are intentionally strict and explicit.

They support:

  • fail-next style behaviour
  • staged failures
  • ordering assertions
  • source/reason capture
  • rollback simulation
  • partial-mutation simulation
  • repeatable edge-case testing

This allows difficult transaction and compensation paths to be tested reliably.

❌ What These Tests Do NOT Claim

The tests do not claim:

  • the framework is bug-free
  • every possible game economy is covered
  • multiplayer correctness is guaranteed
  • third-party adapters are validated
  • all project-specific authority rules are covered
  • every custom currency or inventory implementation is safe
  • all external integrations behave correctly
  • performance or stress limits are proven

The tests validate RevFramework Economy behaviour and guarantees — not every possible project implementation.

🧩 The Philosophy

RevFramework systems are designed around:

  • explicit guarantees
  • predictable behaviour
  • transparent failure handling
  • modular integration seams
  • honest compensation semantics
  • public API safety

The Economy tests exist to lock those guarantees down over time as the framework evolves.

The goal is not to pretend transactions can never fail.

The goal is to make failure behaviour understandable, stable, and intentional.

Economy deliberately avoids pretending that every mixed currency/item flow is perfectly atomic.

Instead, it documents and tests:

  • what is attempted
  • what is rolled back
  • what may remain applied
  • which result code is returned
  • which layer owns the final authority

That honesty matters.

TL;DR

The Economy tests are designed to protect guarantees, not pretend software can never fail.

Hostile tests validate supported public behaviour.

InternalTruth tests protect hidden framework assumptions.

Compensation tests lock down rollback expectations.

Escrow tests validate staged hold / commit / release behaviour.

Together, they help keep Economy predictable as RevFramework evolves.