docs: add DESCENSUS addendum 1 and SIMULATOR vision

docs/DESCENSUS-addendum-1.md

@@ -0,0 +1,193 @@
+# DESCENSUS — Addendum 1
+## Cost Structure and Exploit Closure
+### Status: Canonical. Do not alter without project owner instruction.
+### Date: 2026-05-02
+### Extends: docs/DESCENSUS-genesis.md
+
+---
+
+## Purpose of This Addendum
+
+The genesis document establishes what DESCENSUS is and how the epoch
+filter operates. This addendum closes the exploit loops that code
+cannot close alone. Each principle here describes a cost structure
+that is not enforced by rules — it is enforced by the honest operation
+of the simulation's physical and social reality.
+
+Where code fails to implement these principles completely, this document
+is the authority. Implementation catches up to the document, not the
+reverse.
+
+---
+
+## Principle 1 — Distance Is Elapsed Time
+
+Movement between locations costs simulation days. Those days cannot be
+recovered, compressed, or prepaid. There is no fast travel. There is no
+preparation that eliminates the cost of distance.
+
+A participant who identifies an attack target must travel to reach it.
+That travel consumes elapsed simulation days — days not spent producing,
+building relationships, or developing the clan. The cost is paid before
+the outcome is known.
+
+A participant who wishes to return must travel again. The distance does
+not decrease because the route is now known. Familiarity reduces
+uncertainty, not cost.
+
+**Exploit closed:** A participant cannot accumulate strength and then
+deploy it instantly across distance. Every application of force requires
+elapsed time proportional to distance. The cost of projection is built
+into the geometry of the world.
+
+---
+
+## Principle 2 — Intelligence Decays
+
+Knowledge of another participant's state is accurate at the moment of
+acquisition. It begins aging immediately.
+
+A participant who reaches a target location learns what is there at that
+moment. By the time they return — having paid the travel cost twice —
+the target's state has changed. The intelligence paid for in elapsed
+time is now historical. The participant acts on a record, not a current
+reading.
+
+The longer the return journey, the more the intelligence has aged.
+A distant target that required thirty simulated days to reach has
+changed for thirty simulated days by the time the attacker returns.
+
+**Exploit closed:** A participant cannot acquire perfect intelligence
+and act on it without cost. The act of acquiring intelligence consumes
+the time during which the intelligence remains current. Planning and
+execution cannot be separated from the cost of the interval between them.
+
+---
+
+## Principle 3 — Temporal State Resolution at Minimum Elapsed Time
+
+When two participants occupy the same H3 cell, the encounter is resolved
+at the minimum elapsed simulation time of the two participants.
+
+A participant at day 100 who encounters a participant at day 10 does not
+bring their day-100 strength to the encounter. The encounter resolves at
+day 10. The stronger participant's state is evaluated as it was at their
+own day-10 equivalent — including losses, weaknesses, and resource
+constraints that existed at that point in their history.
+
+The elapsed simulation time of each participant is not visible to others.
+It is not a number on a display. It is inferred from observable signals:
+camp size, tool quality, apparent health of clansmen, the wear on
+structures, the size of food stores. A participant who reads these
+signals carefully can estimate depth. They cannot know it.
+
+The elapsed time of any participant is also in flux. A participant who
+has been active for 100 days but suffered significant losses at day 60
+does not present as a day-100 participant. They present as whatever
+their current state reflects — which may be weaker than a participant
+at day 40 who suffered no losses.
+
+**Exploit closed:** A participant cannot prepare at depth and deploy
+that preparation against a shallower participant. The encounter resolves
+honestly at the point of contact, not at the point of planning.
+Stockpiling Mesolithic weapons for a future DESCENSUS encounter is
+evaluated at the elapsed time of the encounter, not at the elapsed time
+of the stockpile.
+
+---
+
+## Principle 4 — Aggression Is Self-Limiting
+
+A successful attack produces bounded loot, reduced defence, reduced
+production, and reduced reputation for the attacker.
+
+**Loot is bounded.** The target has what the epoch permits and what
+their elapsed simulation time has produced. There is no surplus beyond
+what exists. The attacker cannot extract more than was there.
+
+**Attrition compounds asymmetrically.** The target loses defence and
+production capacity. The attacker loses elapsed time, potential clan
+losses, and reputation. The attacker's cost is paid regardless of
+outcome. The target's loss is recoverable over subsequent elapsed days.
+Repeated aggression against the same target yields diminishing returns
+as the target's loot base depletes and the attacker's reputation
+deteriorates.
+
+**Reputation is a social parameter with real consequences.** In
+Mesolithic social reality, reputation is not an abstract score. It is
+the substrate of alliance, trade, mate exchange, and mutual defence.
+A participant recognised as a marauder by other participants loses
+access to the cooperative structures that make large clans viable.
+Food sharing, territorial agreements, knowledge exchange — all of
+these require a reputation that aggression erodes.
+
+The simulation does not punish aggression by decree. It allows
+Mesolithic social mechanics to operate honestly. A marauder clan
+reaches a natural ceiling imposed by isolation, travel cost, and
+the carrying capacity of territory it must hold alone.
+
+**Exploit closed:** There is no dominant strategy built on aggression.
+Every gain from aggression is offset by costs that compound over elapsed
+time. A participant who attempts to optimise for domination will find
+that domination is self-limiting before it becomes simulation-breaking.
+
+---
+
+## Principle 5 — Abandoned Settlements Are Finite
+
+When a participant quits the simulation, their settlement enters a
+static state. It does not grow, defend itself, or replenish.
+
+A static settlement can be reached, observed, and raided. Its loot
+is finite and does not regenerate. After extraction it is an empty
+location. There are no defenders to defeat and no future production
+to anticipate. It is the least interesting thing a participant can
+engage with.
+
+The simulation does not prevent interaction with abandoned settlements.
+It simply makes them structurally uninteresting as a sustained strategy.
+
+**Exploit closed:** Targeting abandoned settlements is not prohibited.
+It is simply not productive beyond the single extraction event. A
+participant who builds their strategy around abandoned settlements
+is building on a depleting resource base with no renewal.
+
+---
+
+## Principle 6 — The Simulation Does Not Prohibit. It Costs.
+
+There are no forbidden actions in the Simulator. There are only actions
+whose costs, when honestly calculated, make them self-limiting.
+
+This principle supersedes all game-design instincts to add rules,
+restrictions, cooldowns, or penalties. Before any restriction is
+proposed, the question must be asked: does the honest cost structure
+already make this action self-limiting? If yes, no rule is needed.
+If no, the cost structure is incomplete and must be corrected before
+a rule is added.
+
+A rule that overrides the cost structure is a design failure. It means
+the simulation is not honest about what the action costs. Fix the cost,
+not the rule.
+
+**This principle applies to all future addenda.** Each addendum closes
+a loop by identifying the honest cost that code failed to implement —
+not by adding a prohibition.
+
+---
+
+## What This Addendum Does Not Cover
+
+- The specific mechanics of DESCENSUS epoch transition (see genesis document)
+- The Roman epoch cost structure (to be addressed in a future addendum)
+- The Model's role in encounter resolution (to be addressed separately)
+- Multi-participant alliance mechanics (to be addressed in a future addendum)
+- The compression algorithm and its relationship to elapsed time
+  (covered in OTIVM-IV design documentation)
+
+---
+
+*DESCENSUS — Addendum 1 — 2026-05-02*
+*TheRON — single contributor. AI assistants implement, document, flag — do not direct.*
+*Each addendum closes one loop. Addenda accumulate. None supersedes the genesis document.*
+*Where this document and code conflict, this document is the authority.*

docs/SIMULATOR-vision.md

@@ -0,0 +1,269 @@
+# SIMULATOR — Vision Document
+## The Cooperative Simulation and Its Governing Intent
+### Status: Canonical vision. Not an implementation commitment.
+### Date: 2026-05-02
+### Part of: TheRON — CIVICVS / OTIVM / TESSERA / DESCENSUS stack
+
+---
+
+## 1. What This Document Is
+
+This document states what the Simulator is, what it is for, and what
+its two operating modes are. It also identifies four open design
+opportunities — gaps and conflicts that are not blocking but that will
+determine the quality of the final instrument when professional
+development resources are engaged.
+
+This document is not an implementation plan. It is a frame.
+Implementation catches up to the frame, not the reverse.
+
+---
+
+## 2. The Seating Limit
+
+The Simulator accommodates 128 participants. This is a design limit,
+not a technical one. The Simulator is a precision instrument, not a
+mass-market product. Its value comes from the quality of participant
+engagement, not the quantity. A field excavation has a defined team.
+A research vessel has a defined crew. The Simulator has 128 seats.
+
+The seating limit also governs the cooperative simulation's social
+dynamics. 128 is large enough to produce meaningful collective
+behaviour and small enough for each participant to matter individually.
+
+---
+
+## 3. Two Simulation Modes Per Account
+
+Each participant account has access to two simulation modes. These are
+not sequential stages — they are parallel instruments with different
+purposes. A participant may be active in both simultaneously.
+
+---
+
+### Mode 1 — The Single Simulation (The Laboratory)
+
+The participant selects a Mesolithic clan and becomes its Leader.
+
+The single simulation is private and personal. It belongs to the
+participant alone. Its purpose is to produce deep familiarity with
+the substrate: the resource logic, the social mechanics, the cost
+of distance, the consequences of DESCENSUS, the limits of what
+any one clan can achieve.
+
+The participant may restart the single simulation as many times as
+they wish. DESCENSUS ensures that no strategy becomes permanently
+dominant across restarts — every attempt is honest, every environment
+responds to what the participant actually does, not to what they
+planned.
+
+The single simulation has no end condition. It runs until the
+participant is satisfied with what they have learned or with the
+state their clan has reached.
+
+---
+
+### Mode 2 — The Cooperative Simulation (The Instrument)
+
+When a participant is satisfied with their single simulation, they
+may nominate it as their entry into the cooperative simulation.
+
+In the cooperative simulation the participant is no longer a Leader.
+They occupy a role: trader, centurion, magistrate, healer, engineer,
+or others to be defined. The clan they nominated becomes their entry
+state — the foundation from which their role operates.
+
+The Model fills the roles that participants do not occupy. It maintains
+the simulation's historical coherence, populates the consequences of
+participant decisions, and ensures the environment remains faithful to
+the physical and social reality of Mesolithic Central Europe progressing
+toward the Roman epoch.
+
+The cooperative simulation runs forward in time from the Mesolithic
+toward 100 CE. It does not reset. It runs once, together, to
+conclusion. Participants who are active at the end of the simulation
+are ranked by achievement — the definition of achievement is
+deliberately deferred and will be developed as the design matures.
+
+The cooperative simulation is the instrument the entire stack was
+built toward. TESSERA provides the physical substrate. CIVICVS
+provides the Mesolithic environment. OTIVM provides participant
+preparation. DESCENSUS provides the epoch transition mechanism.
+The cooperative simulation is where all of these converge into a
+single shared experience governed by historical reality.
+
+---
+
+## 4. The Model's Role in the Cooperative Simulation
+
+The Model — the Roman Oracle, bounded 100 BCE to 100 CE — fills
+structural roles in the cooperative simulation. It does not play
+to win. It plays to make the simulation real.
+
+The Model never overrides participant decisions. It responds to them.
+Participant decisions that diverge from historical plausibility
+trigger responses that are themselves historically plausible: resource
+scarcity, rival clan formation, disease, extreme weather, political
+consequence. The Model populates the world that participant decisions
+produce, not the world the Model would prefer.
+
+The Model's temporal boundary (100 BCE to 100 CE) means it cannot
+inhabit the Mesolithic from the inside. It reads the record the
+participants create. It interprets that record through Roman
+understanding — which is itself a historically bounded perspective.
+The gap between what the participants experience and what the Model
+can interpret is not a flaw. It is the simulation being honest about
+the limits of Roman knowledge of what came before Rome.
+
+---
+
+## 5. The Transferability of This Design
+
+The design described in this document is not specific to the Roman
+and Mesolithic epochs. Any world that can be encoded in TESSERA and
+governed by an epoch-bounded Model can run this simulation. Rome to
+Mesolithic is the first instantiation. The architecture is open to
+future applications by professional development teams working in
+other historical, geographical, or disciplinary contexts.
+
+This openness is intentional. The data warehouse is the product.
+The simulation is the instrument that fills it. The instrument can
+be replicated.
+
+---
+
+## 6. Open Opportunities
+
+The following four areas are not blocking the current development
+path. They are design gaps and conflicts that will determine the
+quality of the cooperative simulation when it is built. They are
+documented here so that future contributors — assistants, developers,
+domain experts, and participants — can engage with them with full
+context.
+
+No proposals are made here. The conflicts and tensions are described.
+Resolution belongs to future design work.
+
+---
+
+### Opportunity 1 — The Nomination Threshold
+
+**The gap:** The cooperative simulation requires that nominated clans
+be capable of participating without immediately collapsing or
+destabilising the shared environment. But the single simulation
+has no end condition and no defined success state. There is currently
+no mechanism by which the simulation can assess whether a clan is
+ready for nomination.
+
+**The conflict:** A threshold defined too loosely admits clans that
+are not viable and burden the cooperative simulation. A threshold
+defined too strictly prevents participants from nominating until they
+have reached an arbitrary standard that may not reflect actual
+readiness. The threshold must be meaningful without being a gate
+that reproduces the power imbalances DESCENSUS was designed to prevent.
+
+**Why this matters:** The cooperative simulation's balance depends
+on the entry states of its participants. If entry states vary too
+widely, the Model cannot maintain historical coherence without
+overriding participant decisions — which it must not do.
+
+---
+
+### Opportunity 2 — The Model's Balancing Authority
+
+**The gap:** The Model fills roles and responds to participant
+decisions. But the cooperative simulation involves 128 participants
+making decisions simultaneously. The aggregate effect of those
+decisions may produce states that are historically implausible —
+a single clan growing to dominate the region, a resource being
+exhausted before the epoch would permit it, a technology emerging
+before its time.
+
+**The conflict:** The Model cannot override participant decisions
+without breaking the simulation's honesty. But a simulation that
+allows historically implausible states to persist will lose its
+value as a research and educational instrument. The boundary between
+"responding to decisions" and "correcting decisions" is not yet
+defined. Where that boundary sits will determine what kind of
+instrument the cooperative simulation becomes.
+
+**Why this matters:** The Model's authority in the cooperative
+simulation is the most consequential design decision remaining.
+It determines the relationship between participant agency and
+simulation integrity — a tension that does not resolve itself.
+
+---
+
+### Opportunity 3 — The Epistemic Horizon of Participants
+
+**The gap:** A participant who has completed many single simulations
+carries knowledge about the environment that their nominated clan
+does not possess. The clan's knowledge is bounded by what it has
+experienced within the simulation. The participant's knowledge is
+bounded by everything they have learned across all their restarts.
+
+**The conflict:** The simulation cannot technically distinguish
+between a participant playing within their clan's epistemic horizon
+and a participant importing meta-knowledge from previous runs. The
+distinction is real and meaningful — a clan that makes decisions
+based on knowledge it could not have is not a faithful simulation
+participant. But enforcing the distinction requires either technical
+mechanisms that constrain participant agency or a social contract
+that depends on participant integrity.
+
+**Why this matters:** The epistemic horizon problem is present in
+every simulation that allows learning across sessions. It is
+particularly acute here because the single simulation is explicitly
+designed to produce meta-knowledge. The cooperative simulation must
+find a way to value that preparation without allowing it to corrupt
+the simulation's honesty.
+
+---
+
+### Opportunity 4 — The End Condition
+
+**The gap:** The cooperative simulation runs until 100 CE. But
+elapsed simulation time advances differently for different
+participants depending on their activity level, the compression
+ratio, and the state of their clan. The moment at which the
+simulation ends is not yet defined — whether it is a wall-clock
+event, an elapsed-time threshold, a consensus among participants,
+or a declaration by the Model.
+
+**The conflict:** An end condition defined by wall-clock time
+treats all participants equally regardless of how deeply they
+engaged. An end condition defined by elapsed simulation time
+rewards sustained engagement but may disadvantage participants
+who engaged less frequently for reasons outside the simulation.
+An end condition defined by the Model introduces the same
+authority questions raised in Opportunity 2. An end condition
+defined by participant consensus introduces social dynamics that
+may not align with simulation integrity.
+
+**Why this matters:** The end condition governs ranking, data
+preservation, and the simulation's historical closure. How the
+simulation ends determines what it means to have participated in
+it. This decision cannot be deferred indefinitely — it must be
+made before the cooperative simulation is designed in detail.
+
+---
+
+## 7. What This Vision Does Not Commit To
+
+- A launch date or development timeline
+- A specific compression ratio for elapsed simulation time
+- A definition of achievement or ranking criteria
+- A technical architecture for the cooperative simulation's infrastructure
+- A commercial model or licensing arrangement
+- A specific set of participant roles beyond the examples named
+
+These are all open. The vision is the frame. The frame is stable.
+Everything within it is subject to design work that has not yet begun.
+
+---
+
+*SIMULATOR — Vision Document — 2026-05-02*
+*TheRON — single contributor. AI assistants implement, document, flag — do not direct.*
+*This document states intent. It does not constrain the path to that intent.*
+*Future contributors are invited to engage with the four opportunities.*
+*Resolution of any opportunity requires project owner approval before admission.*