REQ-VISUALIZATION-008: correct public shortage-rate and telemetry timing semantics

docs/reference/local-market-guide.md

@@ -56,13 +56,11 @@ This determinism is essential for testing, debugging, and trusting the simulatio
 
 ## Market Expectations
 
-Over many ticks, the market learns approximate patterns through exponential moving averages (EMAs):
+Over time, the market learns approximate patterns through exponential moving averages (EMAs):
 
-- **Expected Use**: The market remembers roughly how much effective demand for this good there is each tick. This is the sum of what all actors want to use, not the sum of what they actually get to use (which may be constrained by rationing). This distinction is intentional: when shortage occurs, the market still learns what buyers actually wanted, not just what they obtained.
-- **Expected Shortage**: The market notes whether shortages are common or rare
-- **Expected Surplus**: The market notes whether surpluses are common or rare
+- **Expected Use**: The market remembers roughly how much effective demand for this good there is each tick, tracked as an EMA. This is the sum of what all actors want to use, not the sum of what they actually get to use (which may be constrained by rationing). This distinction is intentional: when shortage occurs, the market still learns what buyers actually wanted, not just what they obtained.
 
-These expectations are **not** inventories or financial assets. They are just weak memories of past patterns that help inform price adjustments. They cannot be bought, sold, or consumed. A market with zero expected use still sets prices based on current supply and demand.
+This expectation is **not** an inventory or financial asset. It is a weak memory of past patterns that helps inform price adjustments. It cannot be bought, sold, or consumed. A market with zero expected use still sets prices based on current supply and demand, and observed shortages/surpluses do not directly feed back into expectation tracking—only actual effective demand does.
 
 In the first tick a good trades, the market uses current effective demand and sellable supply only. After the first observation, it switches to using the lagged expected-use EMA in the price formula, making price movements less erratic as patterns stabilize.
 

docs/reference/market-settlement-and-taxes.md

@@ -68,12 +68,13 @@ This reconciliation happens automatically each tick. It's a core invariant: the
 Market telemetry records what actually happened, for diagnostics and visualization:
 
 ### Per-Market Telemetry
-After each phase, the market records:
-- **Desired quantity**: How much did buyers want to buy (at their budget limits)?
+The realized M3 observation is produced once per tick, after Phase-8 MAIN local clearing — never after the Phase-4 pre-production pass. The market records:
+- **Desired quantity**: How much did buyers want to buy, before any affordability limit?
+- **Effective demand quantity**: How much of that desired quantity could buyers actually afford to commit? Affordability can make this lower than desired quantity; the two are tracked separately.
 - **Offered quantity**: How much did sellers want to sell?
 - **Cleared quantity**: How much actually changed hands?
-- **Shortage rate**: (desired - cleared) / desired. What fraction of demand wasn't met?
-- **Surplus rate**: (offered - cleared) / offered. What fraction of supply went unsold?
+- **Shortage rate**: `max(0, effectiveDemandQuantity - clearedQuantity) / effectiveDemandQuantity` (zero when effective demand is at or below the numeric epsilon threshold). What fraction of effective demand wasn't met?
+- **Surplus rate**: `max(0, offeredQuantity - clearedQuantity) / offeredQuantity` (zero when offered quantity is at or below the numeric epsilon threshold). What fraction of supply went unsold?
 
 ### Authoritative Economic Transaction Records
 For each sale, the system records two types of authoritative transaction records (not telemetry):