initial upload

docs/training/corpus/Layer_2--Uncertainty/CORPUS-0005-hidden-true-state-vs-known-state.md

@@ -0,0 +1,171 @@
+# CORPUS-0005
+## Hidden True State Versus Known State
+### Status: Training Corpus Seed
+### Layer: Layer_2--Uncertainty
+### Purpose: Teach that the simulation may contain a true state that the actor does not fully know
+### Repository Path: docs/training/corpus/Layer_2--Uncertainty/CORPUS-0005-hidden-true-state-vs-known-state.md
+
+---
+
+## 0. Scenario
+
+A trader in Ostia considers sending oil to Capua.
+
+The simulation has a true current price in Capua.
+
+The trader does not know that true price.
+
+He only knows reports, signals, memories, and claims.
+
+The true state and the known state are not the same.
+
+---
+
+## 1. Hidden True State
+
+The simulation may hold:
+
+| Hidden True State | Value |
+|---|---:|
+| Current Capua oil price | 17 asses |
+| Buyer urgency | low |
+| Rival shipment arrival | already arrived |
+| Available cart space | limited |
+| Warehouse capacity | tight |
+
+These values exist in the world whether the trader knows them or not.
+
+---
+
+## 2. Actor Known State
+
+The trader may know only:
+
+| Actor Known State | Value |
+|---|---|
+| Reported Capua oil price | 22 asses |
+| Report age | three days |
+| Report source | muleteer |
+| Rival shipment | unknown |
+| Cart availability | not yet checked |
+| Warehouse capacity | rumor only |
+
+The actor is not acting on the hidden true state.
+
+He is acting on perceived state.
+
+---
+
+## 3. Why The Difference Matters
+
+A trader can make a rational decision from his known state and still lose because the hidden true state differs.
+
+Example:
+
+Known state suggests:
+
+```text
+expected sale price = 22 asses
+expected total cost = 16 asses
+expected profit = 6 asses
+```
+
+Hidden true state resolves as:
+
+```text
+actual sale price = 17 asses
+actual total cost = 16 asses
+actual profit = 1 as
+```
+
+The decision may have been reasonable.
+
+The outcome is still smaller because the true state differed.
+
+---
+
+## 4. Incorrect Model Behavior
+
+The model should not:
+
+- assume the actor knows the simulation's true state
+- judge the actor's decision only by the final outcome
+- expose hidden values directly in dialogue
+- collapse report, belief, and truth into one value
+- treat wrong belief as irrational when evidence was limited
+- treat hidden true state as player-facing knowledge
+
+---
+
+## 5. Correct Model Behavior
+
+The model should separate:
+
+| Category | Meaning |
+|---|---|
+| true_state | what is actually true in simulation |
+| perceived_state | what the actor believes or estimates |
+| known_evidence | reports, signals, records, observations |
+| confidence | how strongly actor should trust perceived state |
+| action | what actor chooses from perceived state |
+| outcome | what occurs when action meets true state |
+
+The actor acts from perceived state.
+
+The world resolves from true state.
+
+---
+
+## 6. Example Resolution
+
+The trader sends oil because the perceived state shows opportunity.
+
+Later, the sale reveals the current Capua price was lower than reported.
+
+Result:
+
+```text
+perceived opportunity: strong
+decision quality from known evidence: reasonable
+final arithmetic: small profit
+lesson: perception and truth differed
+```
+
+The model should not call the trader foolish merely because the hidden state was unfavorable.
+
+---
+
+## 7. Simulation Use
+
+This principle supports:
+
+- hidden scenario states
+- partial observability
+- confidence tags
+- rumor systems
+- actor perception
+- delayed confirmation
+- fair failure
+- learning from outcome
+
+A good simulation can punish a decision without making the decision stupid.
+
+---
+
+## 8. Layer-0 And Layer-1 Concepts Used
+
+This example uses:
+
+- `Layer_0/CORPUS-0007-information-arrives-unevenly`
+- `Layer_0/CORPUS-0008-rumor-is-uncertain-information`
+- `Layer_0/CORPUS-0012-every-venture-risks-loss`
+- `Layer_1/CORPUS-0003-arithmetic-resolves-the-venture`
+- `Layer_1/CORPUS-0005-rumor-before-confirmed-price`
+- `Layer_2/CORPUS-0001-stale-price-report`
+- `Layer_2/CORPUS-0002-conflicting-reports`
+
+---
+
+## 9. Success Condition
+
+If the model can distinguish what is true in the simulation from what the actor knows, believes, or can reasonably infer, this file is functioning correctly.