diff --git a/docs/product/ECONOMY_AND_BALANCE.md b/docs/product/ECONOMY_AND_BALANCE.md new file mode 100644 index 00000000..222a87a8 --- /dev/null +++ b/docs/product/ECONOMY_AND_BALANCE.md @@ -0,0 +1,444 @@ +# Aetherbound Guild: Economy And Balance Authority + +> Authority: resource movement, rewards, item progression, chapter budgets, +> difficulty modifiers, and balance validation. +> +> Revision: design-batch-01 / 2026-08-10 +> +> [GAME_PRODUCT_CONTRACT.md](GAME_PRODUCT_CONTRACT.md) owns the player promise, +> cadence, and commercial boundary. [SYSTEMS_AND_BATTLE.md](SYSTEMS_AND_BATTLE.md) +> owns combat execution and profession hooks. [SAVE_AND_FAILURE_CONTRACT.md](SAVE_AND_FAILURE_CONTRACT.md) +> owns transaction and recovery behavior. Content documents own the names and +> instances of the 30 adventurers, 36 professions, 100 enemies, 8 chapters, and +> 320 equipment/items. + +## 1. Economy Invariants + +1. All gameplay resources are earned in play. There is no premium currency, + paid energy, ad reward, timer, loot box, login streak, or online-only claim. +2. Every source and sink is visible before commitment and is recorded in the + encounter result. A failed or cancelled operation spends nothing. +3. A resource can be scarce enough to create a choice, but never so scarce that + a first-campaign baseline counter requires grinding a random drop. +4. The same item is not universally better than another item in its band. An + upgrade may increase a budget term only when it also declares an interaction, + timing, targeting, route, or risk change. +5. Reward generation is seeded and stream-separated from combat. The save + authority stores the seed and operation IDs, so replay and recovery cannot + duplicate rewards. +6. The first campaign is solvable with the deterministic acquisition paths and + the starting roster. Optional collection and high difficulty may ask for + broader mastery, never mandatory payment or idle time. + +## 2. Resource Ledger + +These stable resource IDs are the only persistent economy resources. `Supplies` +and `Strain` are expedition state defined by the systems authority; they are +listed here because their conversion affects balance. + +| ID | Player name | Type/cap | Sources | Sinks | Failure treatment | +|---|---|---|---|---|---| +| `crown` | Crowns | Spendable, no hard cap; soft reserve target 600 | Conflict, hazards, anchors, salvage, chapter objectives | Recruit, shop refresh/lock, craft fee, upgrades, route tolls | Unsecured Crown rewards follow difficulty; banked Crowns never disappear | +| `fiber` | Loom Fiber | Persistent material, cap 9,999 | Item salvage, hazards, chapter bundles, duplicate protection | Crafting, behavior upgrades, repair blueprints | Banked only; a failed node cannot consume it | +| `shard` | Aether Shard | Persistent meta material, cap 9,999 | Anchor restoration, mastery trials, first-clear objectives | Profession trials, Reweave law unlocks, deterministic tag rerolls | Never lost; grants are idempotent | +| `xp` | Adventurer XP | Per-adventurer progress, level 1-50 campaign / 70 Reweave | Completed encounters and authored objectives | Level thresholds; no currency conversion | Awarded only once per encounter outcome | +| `mastery` | Profession Mastery | Per adventurer/profession/branch; no decay | Using a profession, solving its counter trial, discovery goals | Unlock Adept/Master/branch access; standing orders | Never lost; duplicate award ignored | +| `supplies` | Supplies | Expedition capacity, 6 default, 9 cap | Start-of-expedition allotment, route nodes, anchor bonuses | Recover, secure, scout, reroute, extra profession change | Difficulty-specific amount is shown before commit | +| `strain` | Strain | Per adventurer, 0-3 stacks | Downed/Lost in encounter, failed hazard, hard retreat | Recover at Camp/Anchor or Guild | Never deletes a first-campaign adventurer; 3 stacks blocks deployment | + +`Crown` is deliberately singular in text and `Crowns` in UI. Aether Shards are +not the battle `Aether` meter. No item or facility may create a new persistent +currency without an Owner-approved contract revision. + +## 3. Crown Flow And Solvency + +### 3.1 Encounter Income + +For a node at chapter `C` (1-8), route depth `D` (0-6), risk tier `R` (0 safe, +1 pressured, 2 elite), and objective flag `O` (0/1), the base reward is: + +```text +base_crowns = round(55 + 18*C + 12*D + 30*R + 35*O) +victory_crowns = floor(base_crowns * difficulty_reward_multiplier) +``` + +An authored story node may replace `base_crowns` with a declared bundle, but +the bundle must be within 0.75x-1.35x of the formula at the same depth. An elite +may add one reward choice, not an unbounded Crown multiplier. A failed node +does not grant victory Crowns; its failure disposition is in the save contract. + +An Anchor grants `40 + 20*C` Crowns for restoring its route, once per campaign +slot. A first-clear objective grants `60 + 25*C` Crowns and `1 + floor(C/3)` +Aether Shards. Replaying a cleared objective grants ordinary node rewards only. + +### 3.2 Crown Sinks + +| Action | Formula | Tunable bounds and reason | +|---|---|---| +| Recruit a named adventurer | `90 + 12*C + 5*max(0, roster_size-6)` | 102-250 Crowns; story recruits may waive cost | +| Shop refresh at Anchor | `min(60, 10 + 5*refreshes_this_anchor)` | Resets at Anchor; prevents infinite fishing | +| Lock a shop offer | `8 + 2*locked_offers` | 8-16 Crowns, disclosed before lock | +| Shop quality investment | `180 + 60*shop_level` | Levels 0-4; each level changes pool tags, not a flat damage bonus | +| Crafting service fee | `30 + 15*tier` | 30-90 Crowns; material cost remains meaningful | +| Item behavior upgrade fee | `40 + 25*tier + 10*band` | `band` is 0-7; no upgrade exceeds 240 Crowns | +| Route toll | `20 + 10*C + 10*R` | Only on a declared shortcut; never required to reach an Anchor | +| Optional training replay | 0 | No reward and no resource sink; preserves learning | + +`refreshes_this_anchor` and `locked_offers` are expedition counters. A player +cannot reset the counters by closing the game or reloading an older snapshot; +the save journal makes the counter increment atomic with the purchase. + +### 3.3 Crown Budget Check + +The baseline campaign starts with 240 Crowns, two authored adventurers, four +starter items, and six Supplies. A solvency run uses the lowest deterministic +reward in each chapter and buys at least one counter item and one recruit per +chapter. It must satisfy: + +```text +banked_crowns_after_chapter(C) >= 80 + 20*C +required_counter_purchase(C) <= 0.45 * expected_chapter_income(C) +``` + +The player may be Crown-poor after an optional elite, but a safe route and a +deterministic counter reward must restore solvency within the next expedition. +No chapter may require more than three refreshes to expose a legal counter. + +### 3.4 Unused Supplies Conversion + +After a successful expedition closes at an Anchor, or after a voluntary route +withdrawal, unused Supplies convert once and the expedition Supply balance +becomes zero: + +```text +supply_crown_bonus = min(80, 8*unused_supplies + 4*chapter) +``` + +A defeated expedition receives no conversion bonus. The conversion operation is +atomic with expedition close, so reload or duplicate confirm cannot pay twice. +The 80-Crown cap keeps preserving Supplies valuable without making avoidance of +recovery universally correct. + +## 4. Materials, Salvage, And Crafting + +### 4.1 Item Budget And Tiers + +The 320 catalog entries are divided into eight chapter bands of 40 entries. +Each band contains 16 Focus, 12 Garb, 8 Relic, and 4 Tool entries. Content may +move a row between slots only with a documented replacement row; the total stays +320. Each band has five tier steps (`0` starter through `4` capstone) and at +least 15 behavior-changing rows. Across the catalog, at least 120 rows pass the +behavior test below; the remaining rows may be stat-focused but still need a +counterfactual use case. + +An item declares a `budget` from the systems stat vocabulary: + +```text +item_budget = 60 + 10*chapter_band + 12*tier +``` + +The row may spend the budget on Power, HP, Guard, Ward, Tempo, Initiative, +status Potency/Tenacity, or one named behavior hook. A behavior hook consumes +10-28 budget points depending on scope. A single row cannot spend more than 55% +of its budget on generic Power/HP/defense. The remainder is a visible tradeoff. + +### 4.2 Behavior-Changing Test + +An item is counted among the required 120 only when removing it from a fixed +company changes at least one observable event in two validation encounters: + +```text +behavior_change = legal_action OR target_set OR timing_window OR + formation_relation OR resource_conversion OR status_rule OR + route_option OR risk_exposure OR profession_identity +``` + +The validation record must name the removed hook, before/after event, cost, and +the two encounters. A conditional `+N%` with the same target, timing, and route +is not a behavior change. The catalog may not use rarity, color, or a larger +number as the only difference between two rows. + +### 4.3 Salvage + +Salvaging an item at the Guild is a single atomic operation. For tier `T`, band +`B`, and item base budget `P`: + +```text +fiber_yield = 1 + floor(T/2) +shard_yield = 1 if T >= 3 and the row has a behavior hook, else 0 +crown_yield = floor(4 + 6*T + P/50) +``` + +The UI previews all yields. A locked item, equipped item, or item referenced by +an active loadout cannot be salvaged until the player explicitly unequips or +removes the lock. Batch salvage requires a review of the exact stable IDs. + +### 4.4 Crafting And Upgrades + +Recipes are deterministic and preview the output stable ID and its possible +behavior branch. A recipe consumes two or three declared source rows, `2 + T` +Loom Fiber, and `1` Aether Shard for tier 3-4 outputs. It may not consume a +random source that has no deterministic fallback. + +For a behavior upgrade from tier `T` to `T+1` at band `B`: + +```text +crowns = 40 + 25*T + 10*B +fiber = 2 + T +shards = 1 if T >= 2 else 0 +``` + +The upgraded row must exchange or refine a hook, not simply multiply all +coefficients. A row has at most two behavior upgrades in the first campaign. +At tier 4, a player may instead unlock one alternate behavior branch by +spending the same cost and a named mastery trial; both branches remain +reversible at the Guild. + +### 4.5 No Hidden Item Tax + +There is no durability, repair timer, inventory rent, or item destruction on +defeat. A player may keep all 320 catalog entries in a fixed-capacity archive; +the practical limit is equipped copies, not a storage expansion purchase. + +## 5. XP, Mastery, And Profession Investment + +### 5.1 XP Curve + +For character level `L` (1-49), the XP required to reach `L+1` is: + +```text +xp_to_next(L) = floor(95 * L^1.35) +``` + +Encounter XP is: + +```text +encounter_xp = floor((50 + 25*C + 10*D + 35*R + 20*O) * xp_multiplier) +``` + +Deployed adventurers receive 100% of encounter XP; reserves receive 60% when +the company wins without being deployed. An adventurer who is Downed receives +50% of the award, and one Lost for the encounter receives 25%. There is no XP +for a failed node, but the player keeps any previously banked XP. XP beyond the +level cap is not converted into another resource. + +The Guild offers a no-cost catch-up grant to an adventurer more than eight +levels below the chapter band: + +```text +catch_up_xp = min(0.35 * xp_to_next(target_level), + xp_to_next(target_level) - current_level_xp) +``` + +It is available once per Anchor and cannot leapfrog the chapter level cap. + +### 5.2 Mastery + +Base profession Mastery gains per completed encounter are: + +```text +mastery = 2 + min(3, distinct_profession_hooks_used) + + 2*(previewed counter tag answered) + 3*(signature used) +``` + +The per-encounter cap is 12. A branch trial grants 40 Mastery once. A base +reaches `Adept` at 100 and `Master` at 300; advanced branch mastery uses the +same 300 threshold. Repeating a training replay grants no XP, Mastery, or +rewards. Mastery is proof of use, not a mandatory permanent stat tax. + +### 5.3 Aether Shard Meta Progression + +Aether Shards are earned from first-clear objectives, Anchor restoration, and +behavior-changing item discovery. In the first campaign they unlock authored +profession trials and archive views; they do not add raw combat percentages. +Postgame Reweave law unlocks cost 12-30 Shards each and are finite. A player +can earn every required trial Shard on deterministic routes before the final +campaign confrontation. + +### 5.4 Recruitment + +All 30 adventurers are authored, unique, and persistent. The campaign begins +with two. Each of the remaining 28 has one authored availability chapter and one +deterministic recruitment objective. A route draft may reveal a recruit early, +but random generation cannot make that recruit permanently unavailable. + +Accepting recruitment pays the Crown formula in Section 3.2 and adds the +adventurer once. Deferring adds the candidate to the Guild board. If the +availability chapter is `A`, the fixed deferred cost in later chapter `C` is: + +```text +deferred_recruit_cost = ceil(cost_at_availability * + max(0.50, 1 - 0.10*max(0, C-A))) +``` + +This makes a missed opportunity recoverable without a grind wall. Recruits +cannot be duplicated, sold, sacrificed, or permanently dismissed. A full active +company sends the new recruit to the roster bench without unequipping anyone. + +The content package must expose all 12 base professions through available +recruits by the end of Chapter 3 and make all 30 recruits deterministically +available by the final Chapter 8 Anchor. Recruitment never depends on a shop +refresh or a specific random item. + +## 6. Loot, Route Rewards, And Bad-Luck Protection + +At an Opportunity or Elite node, the player sees three reward cards: one +guaranteed tag-directed card, one deterministic material bundle, and one +seeded choice. The guaranteed card is selected from the requested counter tag +or the chapter's current item band. Declining it is legal and visible. + +The reward stream uses `reward` only; it cannot alter `critical` or +`target_tie` streams. Bad-luck protection is deterministic: + +```text +if two consecutive eligible drafts omit a requested tag: + the third eligible draft contains that tag +``` + +The protection resets after the tagged card is offered, not after the player +accepts it. A tag request is chosen at an Anchor and may be changed for free. +It cannot name a specific item until that item has been discovered in the +archive, preventing an early catalog lookup from becoming a guaranteed best +build. + +An immediate-secure reward pays 80% of the card's Crown value and banks it; +accepting it into the Unsecured Cache pays 100% but exposes it to the active +difficulty contract. This is a deliberate risk tradeoff, not a hidden fee. + +## 7. Difficulty Contracts + +Difficulty changes failure meaning and reward exposure, not the availability of +counterplay. The first campaign defaults to `Wayfinder`. + +| Contract | Defeat/retreat | Reward multiplier | Supplies | Intended use | +|---|---|---:|---:|---| +| Wayfinder | Lose 25% of Unsecured Cache value, +1 Strain to each Downed/Lost unit (at most two affected units), recover at Anchor if eligible | 1.00x | 6 | Learning and normal campaign | +| Stormbound | Lose 50% of Unsecured Cache value, +1 Strain to every deployed Downed/Lost unit, recover at Anchor if eligible | 1.15x | 6 | Active campaign | +| Iron Oath | Lose all Unsecured Cache, +2 Strain to Downed/Lost units, close route and expedition at Guild | 1.30x | 5 | Adversarial/high-risk campaign | +| Reweave law: Frayed Routes | On defeat one revealed node is reshuffled, no extra loss; route previews remain complete | 1.10x | 7 | Postgame variation | +| Reweave law: Scarce Anchors | Secure costs +1 Supply and withdrawal banks 75% of Cache | 1.25x | 5 | Postgame mastery | + +No campaign or Reweave contract defined here permanently deletes or retires an +adventurer. High difficulty increases exposed rewards, route loss, Supplies, +and Strain pressure instead of converting the roster into disposable currency. + +Exact Supply consumption, battle retreat, withdrawal, Anchor eligibility, and +failure transaction ordering are owned by the save/failure authority. + +`difficulty_reward_multiplier` is applied once to a reward operation and is +rounded down. It never multiplies XP or Mastery, so difficulty cannot become a +mandatory farming route for profession access. + +## 8. Chapter Pacing Budget + +These budgets are the balance target for a normal profile. Active players may +finish 10% faster through legal automation; adversarial players may take 20% +longer through recovery and optional elites. There are no timers that force +waiting. + +| Chapter | Expeditions | New decision pressure | Target minutes | First-clear Shards | Item bands | +|---:|---:|---|---:|---:|---| +| 1 | 6 | protection and first telegraph | 180-195 | 4 | 0 | +| 2 | 7 | displacement and lane exposure | 195-210 | 5 | 0-1 | +| 3 | 7 | status timing and branch access | 205-220 | 6 | 1-2 | +| 4 | 8 | multi-lane objectives | 210-225 | 7 | 2-3 | +| 5 | 8 | resource conversion and barriers | 220-235 | 8 | 3-4 | +| 6 | 8 | cast chains and reserve rotation | 220-240 | 8 | 4-5 | +| 7 | 9 | combined old/new pressure | 230-250 | 9 | 5-6 | +| 8 | 9 | final rupture and counterfactual mastery | 240-270 | 10 | 6-7 | + +The chapter midpoint must have a safe Anchor, a deterministic counter item, and +at least one branch trial. A chapter's final confrontation may consume up to +two normal expeditions of time but must present a new choice at each phase. +The sum of the lower bounds is 1,700 minutes (28.3 hours); active mastery and +route familiarity bring the first-campaign target into the frozen 25-35 hour +window without idle income. + +### 8.1 Cumulative Completion Budget + +| Milestone | Additional authored play after prior milestone | Cumulative target | Required work, never waiting | +|---|---:|---:|---| +| First campaign ending | 25-35 h | 25-35 h | Eight chapters and final confrontation | +| Build completion | 30-40 h | 60-75 h target, 80 h hard budget | Remaining branch trials, counterfactual encounters, profession mastery, build variants | +| Collection/high difficulty | 20-30 h | 85-105 h centered near 100 h | Deterministic catalog gaps, Reweave laws, final challenge fixtures | + +The cumulative total is a breadth target, not a retention promise. Repeated +completion of an unchanged encounter may contribute at most 20% of any +milestone's additional hours. The rest must come from new branch comparisons, +route laws, item interactions, enemies, or authored mastery trials. + +## 9. Pacing Simulation Profiles + +The following assertions are required for a representative 20-minute session +and for a full-campaign budget run. They make the product contract measurable. + +| Profile | Preparation behavior | Route behavior | Intervention behavior | Expected resource posture | Required assertions | +|---|---|---|---|---|---| +| Normal | One counter loadout change per 1-2 nodes | Mixes safe and pressured nodes | One manual Directive per battle | Ends an expedition with 1-3 Supplies and 50-150 Crowns | >=6 meaningful decisions/20 min; no gap >150 s | +| Active | Compares two builds and formation lines | Selects a branch after each preview | Uses both charges when legal; pauses at telegraphs | Lower Supplies, higher secured reward | >=10 decisions/20 min; no gap >120 s | +| Efficient | Uses standing orders on mastered routine | Chooses shortest viable path | Manual only on unmastered tags/exception | Retains 2+ Supplies for conversion | >=4 decisions/20 min; no gap >165 s | +| Adversarial | Keeps a fragile synergy for elite rewards | Presses Cache until 2+ Strain or phase risk | Saves a charge for the final phase | Cache variance is high but positive over 3 expeditions | >=8 decisions/20 min; no gap >135 s | +| Returning | Reads a 90-second recap and changes one rule | Resumes at last Anchor or chooses a known route | Replays one diagnostic before commitment | Starts with the same banked resources; no catch-up gift beyond defined grant | >=3 decisions/12 min; no gap >150 s | + +For each profile, a balance run records `decision_time`, `decision_kind`, +`state_before`, `available_actions`, `chosen_action`, and `state_after`. A +choice is meaningful only when two legal actions produce different expected +outcomes under the current state. A report that lists only reward claims does +not satisfy this audit. + +## 10. Balance Gates And Anti-Dominance Tests + +The numeric package is ready for implementation only when these checks pass: + +1. **Solvency:** the lowest-reward Wayfinder run reaches every chapter Anchor, + buys at least one deterministic counter item per chapter, and reaches the + final confrontation with 80 + 20*chapter Crowns in reserve. +2. **Frontier:** for each fixed encounter, at least two loadouts have a 60%+ + simulated clear rate over the declared reward seed set, and their advantage + switches on a follow-up encounter with a different pressure tag. +3. **Item diversity:** at least 120 catalog rows pass the two-encounter + behavior-changing test; no ten-row sample has more than six rows whose only + useful effect is generic Power/HP/defense. +4. **Route diversity:** across three seeded route graphs, the optimal node + choice differs for at least two of the five pacing profiles. +5. **Failure recovery:** after three consecutive defeats, Wayfinder can return + to a viable counter build within two expeditions without a random drop. +6. **Decision density:** no profile has a gap above its table threshold or a + battle that reaches the 180-second Fracture defeat in more than 5% of normal + seeds. +7. **Inflation:** by Chapter 8, a normal player can afford one upgrade and one + craft every two expeditions while retaining a meaningful refresh decision; + Crowns must not become irrelevant before the final Anchor. +8. **Postgame:** all finite Reweave laws and branch trials are reachable by + roughly 60-80 hours; collection/high-difficulty completion has a visible + terminal state around 100 hours. + +Any failed gate is reported with the earliest failing resource or encounter +fixture. Tuning may change constants only within the ranges in this document; +changing a resource's meaning requires a product/spec revision. + +## 11. Fixed Economy Test Vectors + +| Vector | Inputs | Expected result | +|---|---|---| +| Crown reward | C=3, D=2, R=1, O=1, Wayfinder | `floor(55+54+24+30+35)=198` Crowns | +| Refresh cap | 12 refresh attempts at one Anchor | Costs 10,15,...,60 then remains 60; no negative balance | +| Salvage | T=3, B=4, P=144 | 2 Fiber, 1 Shard, `floor(4+18+2)=24` Crowns | +| Upgrade | T=2, B=5 | 130 Crowns, 4 Fiber, 1 Shard; one behavior branch only | +| XP | C=2, D=3, R=1, O=0, Wayfinder | `50+50+30+35=165` XP per deployed unit | +| Mastery cap | Signature + two distinct hooks + counter | 9 Mastery before the per-encounter cap | +| Cache choice | 100-Crown card, immediate secure | 80 banked Crowns; no Unsecured Cache entry | +| Bad luck | Two eligible drafts omit requested tag | Next eligible draft includes the tag | +| Supplies conversion | 3 unused Supplies at Chapter 4 | `8*3+4*4=40` bonus Crowns, paid once at expedition close | +| Difficulty | 200-Crown Cache, Stormbound defeat | 100-Crown value removed; banked Crowns untouched | + +## 12. Authority Checklist + +- [ ] Resource IDs, sources, sinks, caps, and failure treatment are explicit. +- [ ] All item tiers and the 120 behavior-changing requirement have a test. +- [ ] Crown, XP, Mastery, crafting, reward, and difficulty formulas are fixed. +- [ ] Eight chapter budgets sum to the 25-35 hour campaign target. +- [ ] Normal, active, efficient, adversarial, and returning profiles have + decision timestamps and maximum no-decision gaps. +- [ ] Solvency, inflation, anti-dominance, recovery, and postgame gates are + defined without a paid or idle progression path. diff --git a/docs/product/GAME_PRODUCT_CONTRACT.md b/docs/product/GAME_PRODUCT_CONTRACT.md new file mode 100644 index 00000000..9f46d68e --- /dev/null +++ b/docs/product/GAME_PRODUCT_CONTRACT.md @@ -0,0 +1,576 @@ +# Aetherbound Guild: Game Product Contract + +> Authority: player promise, scope, experience cadence, progression shape, and +> product boundaries for the complete pre-production package. +> +> Revision: design-batch-01 / 2026-08-10 +> +> Companion authorities: +> [SYSTEMS_AND_BATTLE.md](SYSTEMS_AND_BATTLE.md), +> [ECONOMY_AND_BALANCE.md](ECONOMY_AND_BALANCE.md), and +> [SAVE_AND_FAILURE_CONTRACT.md](SAVE_AND_FAILURE_CONTRACT.md). + +## 1. Authority And Decision Order + +This document answers what the game promises and why a system exists. The +systems document owns combat and progression mechanics, the economy document +owns numeric pacing and resource movement, and the save/failure document owns +transaction and recovery behavior. When wording conflicts, use this order: + +1. Frozen repository specification and Owner decisions. +2. Save and transaction safety rules. +3. Explicit formulas and boundaries in the systems and economy authorities. +4. This product intent. +5. Content, presentation, and prototype instances. + +The design is implementation-ready but is not evidence that the experience is +fun, understood, visually accepted, device-safe, or ready for production. +Those remain later prototype, independent-review, and Owner gates. + +## 2. Product Definition + +**Aetherbound Guild** is a premium, landscape 2D party-building strategy RPG. +The player leads a magic guild restoring a network of ruptured aether routes. +They recruit persistent adventurers, assign professions and skill loadouts, +equip them, arrange a six-person formation, choose a route, and watch a +deterministic auto-battle execute their preparation. During battle, the player +may spend at most two Command charges on prepared tactical directives. + +The product is not an idle game, gacha, live-service treadmill, or action RPG. +Its skill is diagnosis and preparation: + +```text +read a visible threat +-> predict the party's first failure point +-> change one or more high-leverage rules +-> watch those rules execute +-> compare prediction with result +-> secure rewards or accept more risk +-> permanently change the guild and the next route +``` + +### 2.1 Audience + +Primary players enjoy party composition, job systems, equipment interactions, +route planning, and the satisfaction of seeing a prepared plan work. They want +meaningful strategy without continuous high-frequency control. + +Secondary players include completionists who want to master all 36 professions +and 320 items, and challenge players who want stricter route modifiers after a +finite campaign ending. + +The game must remain usable by players who pause often, play in 8-20 minute +segments, use touch only, or return after a long break. + +### 2.2 Fixed Commercial And Platform Boundary + +| Field | Contract | +|---|---| +| Business model | One-time premium purchase; no ads, loot boxes, paid energy, paid currency, battle pass, daily streak, or pay-to-skip | +| Platforms | Landscape 16:9 target for mobile, PC, and console; current design must support touch, mouse, keyboard, and controller semantics | +| Languages at first release | English and Simplified Chinese, authored from message IDs rather than concatenated strings | +| First campaign | 25-35 hours, eight authored chapters, finite ending | +| Build completion | 60-80 hours for broad profession/build mastery | +| Collection/high difficulty | Approximately 100 hours, with a visible completion state rather than endless obligation | +| Connectivity | Core campaign fully offline; optional platform services may never gate play or save access | +| Formal development | Frozen until complete design, independent review, and explicit Owner approval | + +Future paid expansions may add authored chapters after release, but may not +sell power, random rewards, timers, or relief from deliberately created +friction. Such an expansion is outside this design authority. + +## 3. Player Fantasy And Emotional Arc + +The player is the guild's strategist, not a distant spectator and not a +puppeteer issuing every attack. Adventurers have stable identities and execute +the rules the player prepared. The fantasy progresses through four scales: + +| Scale | Player fantasy | Required emotion | +|---|---|---| +| Seconds | Read a clean magical skirmish and see a prepared rule fire | Comprehension, then confirmation | +| Expedition | Guide a company through a risky branch of the ruptured network | Anticipation, tension, adaptation | +| Chapter | Restore a regional anchor and make the guild capable of a new kind of expedition | Competence and transformation | +| Campaign/postgame | Reconnect the world, then deliberately reweave it under harder laws | Ownership, mastery, curiosity | + +The expected emotional sequence around failure is: surprise no longer than +three seconds, a legible cause, a credible countermeasure, and an immediate +safe place to try that countermeasure. Failure may cost route opportunity but +must not erase understanding or named-character attachment. + +## 4. Experience Pillars + +### 4.1 The Battle Honors Preparation + +Targeting, timing, formation protection, status resolution, and directive +execution are deterministic from visible inputs and a stored seed. A unit may +fail to follow an order only for a named, inspectable reason. The battle report +must identify that reason. + +### 4.2 Every Threat Changes The Best Answer + +Encounter previews expose mechanics, lanes, timing, defenses, and reward risk. +At least two rational responses must exist for every required campaign threat. +Their value must vary with current health, roster, supplies, equipment, +unsecured rewards, and route position. + +### 4.3 Named Adventurers Become A Guild History + +All 30 recruits are authored characters rather than disposable random units. +Their profession mastery, signature interactions, injuries, and chapter +participation persist. No standard campaign rule permanently deletes one. + +### 4.4 Randomness Presents Problems, Not Verdicts + +Route generation, reward drafts, and seeded combat details can vary, but the +player sees bounded choices, tag-directed acquisition, and bad-luck protection. +Required build pieces always have a deterministic acquisition route. + +### 4.5 Completion Changes The Next Cycle + +Restoring an anchor changes available routes, guild services, profession +branches, and world rules. Solved routine encounters may gain conditional +automation, but new mechanics remove that automation's certainty. The next +cycle begins with inherited consequences and a different planning question. + +## 5. Anti-Pillars And Design Vetoes + +Reject a feature or content row if it depends on any of the following: + +- watching numbers rise without a new state-dependent decision; +- an auto-battle rule that can silently disregard formation or targeting; +- a higher rarity or power rating that is always the correct item choice; +- random acquisition without a visible deterministic fallback; +- permanent-stat grinding required to make baseline difficulty fair; +- manual repetition after the player has already demonstrated mastery; +- automation that removes the strategic decision along with routine labor; +- hidden recipes, hidden immunity, or surprise targeting exceptions; +- a battle longer than three minutes with no new decision opportunity; +- deleting a named character, save, item, or irreversible choice without a + clear confirmation and recovery boundary; +- daily/weekly obligations, real-time construction waits, or offline income; +- monetization, social comparison, or collection volume used to conceal a + weak core loop; +- copied names, formulas, layouts, prose, progression topology, or expression + from the authorized comparison material. + +## 6. Canonical Terms And Content Envelope + +These terms are shared keys. Other design documents must not introduce a +synonym for the same state. + +| Term | Definition | +|---|---| +| Guild | Persistent player organization, roster, facilities, inventory, and campaign record | +| Adventurer | One of exactly 30 named recruitable characters | +| Company | Up to six deployed adventurers plus up to two expedition reserves | +| Profession | One active combat discipline; exactly 12 base professions and 24 advanced professions | +| Loadout | Profession skills, equipment, tactical directives, and formation position assigned before battle | +| Weave Grid | Three lanes by two ranks; the six legal deployment slots | +| Directive | A prepared, player-triggered tactical intervention that spends one Command charge | +| Encounter | One battle or noncombat decision node with a committed outcome | +| Expedition | One 8-20 minute route segment of four to seven nodes ending at an anchor or withdrawal | +| Chapter | A regional arc of multiple expeditions culminating in a persistent anchor restoration | +| Anchor | A safe route checkpoint that banks unsecured rewards and persists chapter progress | +| Unsecured Cache | Rewards earned since the last anchor and still exposed to defeat consequences | +| Supplies | Bounded expedition capacity spent on recovery, securing, scouting, or rerouting | +| Strain | Temporary adventurer injury, from zero to three stacks, cleared at the Guild | +| Mastery | Non-spend progress proving use of a profession or encounter solution | +| Reweave | Post-campaign cycle that preserves collection while changing route laws and build constraints | + +The fixed authored content envelope is: + +- exactly 30 named recruitable adventurers; +- exactly 12 base professions, each with exactly two advanced branches, for 24 + advanced and 36 total profession identities; +- exactly 100 enemy combat identities across exactly eight chapters; +- exactly 320 equipment/item entries; +- at least 120 item entries whose behavior-change declaration passes the test + in the economy authority. + +Content owns names and instances. Product systems own schemas, counts, +validations, and the purpose of every row. + +## 7. Readability And Input Cadence + +### 7.1 Three-Second Read + +Within three seconds of entering an encounter preview or returning attention to +battle at 1x, the player must be able to identify: + +1. which three lanes are contested; +2. which allied front slot protects each rear slot; +3. the enemy's next major telegraphed action and countdown; +4. the allied unit at greatest immediate risk; +5. current Command charges and whether a directive is legal; +6. whether rewards are secured or currently at risk. + +This is a presentation and usability gate, not a claim that the current design +already passes human comprehension. + +### 7.2 One-To-Ten-Second Actions + +The common action set must resolve with immediate authoritative feedback: + +| Action | Target completion | Immediate result | +|---|---:|---| +| Select a route node | 1-3 s | Threat/reward comparison and projected cache risk update | +| Inspect a telegraph or status | 1-3 s | Plain-language cause, timing, targets, and counter tags | +| Move a unit between legal slots | 2-5 s | Protection lines, reach, and predicted first target update | +| Equip or compare an item | 2-8 s | Stat delta plus behavior/skill timing delta | +| Change one skill or standing order | 2-8 s | Validity check and affected battle events preview | +| Fire a directive | 1-4 s | Simulation pauses for targeting if needed, then confirms cost and effect | +| Secure, recover, scout, or reroute | 2-10 s | Supplies and exposed-reward state update atomically | + +No accepted tap, click, key, or controller action may wait for a decorative +animation before committing. Animation follows state and is skippable. + +### 7.3 Thirty-To-180-Second Choices + +Every 30-180 seconds during active expedition play, the state must ask a real +question such as: + +- counter a visible cast or preserve Command for a later phase; +- keep a fragile damage plan or trade output for lane protection; +- spend Supplies to heal, expose the cache and press on, or bank it early; +- take a targetable equipment reward or a higher-value unknown reward; +- rotate in a reserve and accept a weaker profession link; +- use a mastered standing order or manually hold it for an exception; +- pursue the chapter objective or detour for a recruit/mastery objective. + +Two consecutive nodes may never have the same optimal answer for all valid +company states. A sequence with no meaningful player decision for more than +180 seconds fails the design, even if effects and rewards occur during it. + +## 8. Complete Player Loop + +### 8.1 Guild Preparation + +```text +read chapter pressure and next anchor objective +-> inspect roster health, mastery, and missing counter tags +-> select six deployed and up to two reserves +-> choose professions, skill loadouts, equipment, grid slots, and directives +-> choose one route entrance with explicit threat/reward information +``` + +The Guild is safe. Equipment and learned skill respec are free here. The scarce +decision is what the limited company and inventory can cover, not a respec tax. + +### 8.2 Expedition + +```text +preview two or three reachable nodes +-> choose route +-> prepare against the committed preview +-> resolve encounter +-> diagnose result +-> draft or decline reward +-> update unsecured cache, Strain, Supplies, and route stability +-> press, secure, recover, scout, reroute, or withdraw +-> reach anchor and bank progress +``` + +Route nodes are face-up once scouted. A selected encounter is not silently +rerolled by leaving its screen. All costs and failure exposure are shown before +commit. + +### 8.3 Chapter Transformation + +Each chapter follows this required progression: + +1. A new rupture rule makes a previously reliable plan incomplete. +2. A safe encounter teaches the rule through visible consequence. +3. A guided route offers two credible counters. +4. Repeated routine handling can be encoded in one standing order. +5. An elite combines the rule with an older pressure and breaks naive + automation. +6. Restoring the regional anchor permanently adds a route, guild service, + profession branch, acquisition method, or formation rule. +7. The next chapter inherits that change and presents a different bottleneck. + +A chapter cannot be approved if its only transformation is larger numbers, +another currency, cosmetic scenery, or an enemy rename. + +### 8.4 Campaign Completion And Reweave + +The first campaign ends after all eight regional anchors are restored and a +final authored confrontation resolves the world's immediate rupture. Credits, +epilogues, collection state, and campaign statistics are visible before any +postgame prompt. + +Postgame offers three finite paths: + +- **Build Mastery:** unlock and validate both advanced branches of every base + profession through authored trials. +- **Collection Completion:** discover the 320-item catalog and the mechanical + interaction attached to each behavior-changing entry. +- **Reweave:** begin a remixed eight-chapter cycle with persistent roster, + knowledge, and collection, but choose two world laws that alter route and + combat value. Item levels normalize to the cycle band so inherited breadth, + not raw overleveling, drives the new plan. + +Reweave is not an infinite content promise. The package defines a final high- +difficulty completion badge and statistics screen around the 100-hour target. + +## 9. Portfolio Incremental Chain + +The game must prove the complete incremental contract through play: + +| Chain step | Aetherbound implementation | Proof required later | +|---|---|---| +| Manual action | Player manually targets a Focus directive and moves a front/rear pairing | Real input causes visible targeting/protection change | +| Immediate result | Target line, cast countdown, damage source, and cache state update in the same interaction | Runtime frame/audio feedback and authoritative state agree | +| Automation | Adventurers execute loadouts and formation rules without attack spam from the player | Deterministic replay matches declared rules | +| Readable bottleneck | Preview/report identifies lane collapse, cast pressure, Strain, Supplies, or missing counter tag | Fresh player can name the bottleneck | +| State-dependent choice | At least two of formation, loadout, directive timing, recovery, securing, and route choice are rational in different states | Counterfactual simulation changes best answer | +| Automate solved labor | A mastered standing order can trigger one routine directive condition | Automation executes only declared condition and reports exceptions | +| Persistent transformation | Anchor restoration changes route/guild/profession/equipment possibility | Save persists transformation and migration preserves it | +| Different next cycle | New rupture or Reweave law invalidates a previously universal routine | Next plan differs for a mechanical reason, not only higher values | + +## 10. Onboarding Contract + +Tutorial content must follow **safe action -> guided decision -> independent +test**. Tooltips alone do not satisfy a teaching step. + +### 10.1 First 20 Minutes + +| Target time | Stage | Player action | Failure safety | Understanding check | +|---:|---|---|---|---| +| 0:00-0:30 | Safe action | Tap/click an unstable lane and place the provided frontliner | No cost; invalid slot snaps back with reason | Player can point to front and protected rear | +| 0:30-2:00 | Immediate battle | Start a 25-45 s deterministic training fight | Cannot lose; speed fixed to 1x for first telegraph | Player sees planned protection intercept damage | +| 2:00-4:00 | Guided decision | Choose either a guard item or an interrupt skill against a shown cast | Both win; report explains different cost | Player predicts which event changes | +| 4:00-7:00 | Independent test | Repeat variant without highlighted answer | Free reset; no reward farming | Chosen counter changes first failure point | +| 7:00-10:00 | Route risk | Choose safe anchor or exposed reward detour | Consequence preview remains on commit | Player states what is unsecured | +| 10:00-14:00 | Intervention | Time one prepared directive against a telegraph | Pause-and-target; missed window can be replayed | Player explains why it was or was not legal | +| 14:00-18:00 | Recovery | Spend one Supply on recovery or preserve it and rotate reserve | Either route remains completable | Player identifies opportunity cost | +| 18:00-20:00 | Independent expedition | Select, prepare, and resolve a complete node without prompts | One free training rewind | Player names next objective and one weakness | + +### 10.2 Teaching Rules + +- Teach no more than one new icon family and one new decision axis per node. +- Suppress a system until it can alter the next decision; never unlock five + menus as a reward dump. +- A tutorial prompt may point at a legal action, but the next encounter must + require recognition without the pointer. +- If the player fails the independent test twice, show the cause chain and let + them enter a no-reward training replay. Do not automatically equip the answer. +- Experienced players may skip dialogue and guided highlights, but must still + pass the independent mechanics test or explicitly open its rule summary. +- Returning players receive a state recap and optional one-node refresher, + never a forced replay of the opening tutorial. + +## 11. Session And Campaign Shape + +| Scope | Target | End state | +|---|---:|---| +| Battle | 35-120 s; hard systemic cap at 180 s | Cause/result report and immediate next choice | +| Expedition | 8-20 min, four to seven nodes | Anchor bank, voluntary withdrawal, or defeat recovery | +| Typical play session | 20-45 min, one to three expeditions | Safe Guild or anchor save point, explicit next objective | +| Chapter | 2.5-4.25 h, six to nine expeditions plus confrontation | Persistent regional transformation | +| First campaign | 25-35 h across eight chapters | Finite ending and postgame choice | +| Build completion | 60-80 h | All profession branches understood and viable | +| Collection/high difficulty | About 100 h | Catalog and final challenge completion state | + +The game may be suspended at any time. A session-ending prompt is never needed +to preserve progress. Short sessions must still end on a meaningful committed +choice, not only an arbitrary stamina or timer boundary. + +### 11.1 Pacing Profiles And Decision-Density Contract + +These are five observed player-behavior profiles, not difficulty settings. The +same encounter seed, item band, and route rules must support all five without +requiring a different product mode. A profile assertion is measured in +simulation seconds; menu navigation and a confirmation tap do not count as a +decision. + +| Profile | Typical behavior | Decisions per 20 min | First meaningful decision | Longest no-decision gap | Completion/session target | +|---|---|---:|---:|---:|---:| +| Normal | Reads previews, changes one or two loadout rules, uses 1x/2x | 6-9 | <= 180 s | <= 150 s | 25-35 h | +| Active | Pauses for telegraphs, spends both Command charges, tests counterfactuals | 10-14 | <= 120 s | <= 120 s | 25-32 h | +| Efficient | Uses mastered standing orders and batch crafting, intervenes on exceptions | 4-7 | <= 180 s at Guild, <= 150 s in an expedition | <= 165 s | 28-35 h | +| Adversarial | Selects elites, presses unsecured Caches, accepts route modifiers | 8-12 | <= 150 s | <= 135 s | 30-35 h including recovery | +| Returning | Reads the recap, makes one deliberate change, then resumes a known route | 3-6 per 12 min | <= 90 s after recap | <= 150 s | 25-35 h in 20-30 min sessions | + +The first expedition has a fixed teaching timeline. The timestamps are target +windows, not scripted cutscenes: + +| Elapsed time | Required player-facing question | Evidence shown before commit | +|---:|---|---| +| 0:00-0:30 | Which slot protects the exposed rear? | Weave Grid relation and first target line | +| 1:30-3:00 | Which of two counters changes the first major event? | Cast tag, counter tags, predicted event | +| 4:00-6:00 | Is the detour worth unsecured risk? | Reward family, failure disposition, Cache value | +| 7:00-10:00 | Spend a Directive now or preserve it? | Command gain forecast and legal target list | +| 10:00-14:00 | Recover Strain, rotate a reserve, or press? | Supply cost, reserve penalty, next-node pressure | +| 14:00-18:00 | Which learned rule can be automated? | Mastery status and standing-order exception | +| 18:00-20:00 | What is the next bottleneck after the Anchor? | Transformation preview and route counter tags | + +During any one expedition, a meaningful choice must occur at least once before +the first battle ends, once after each reward draft, and once before an Anchor +commit. If no state-dependent choice is available for 120 seconds, the route +generator inserts a visible fork, telegraph, recovery trade, or cache decision; +it never inserts a cosmetic prompt. A battle may resolve automatically, but the +result report and next-node preview must expose the next decision within 15 +seconds of resolution. + +The campaign-hour target is calculated from authored chapter budgets rather than +from forced waiting: + +```text +campaign_minutes = sum(chapter_expedition_minutes) + + sum(chapter_confrontation_minutes) +first_campaign_target = 1,500-2,100 minutes (25-35 hours) +``` + +The economy authority supplies the chapter budgets and reward rates. A balance +run fails if any profile exceeds the 180-second maximum gap, if the first +counter decision occurs after eight minutes, or if a chapter reaches its time +budget only by increasing enemy health or adding unskippable animation. + +## 12. Accessibility, Localization, And Input + +### 12.1 Accessibility Baseline + +Required from the first prototype specification: + +- UI scale presets at 100%, 115%, and 130% without clipped functional text; +- safe-area layouts for reference small, standard, and large 16:9 viewports; +- reduced motion, reduced flashes, camera-shake intensity, and hit-stop toggle; +- independent music, ambience, voice, and effects volume plus master mute; +- subtitles/captions for all information-bearing audio with speaker/event tags; +- color-independent lane, rarity, relation, damage, and status encoding; +- high-contrast target and focus outlines; +- hold/toggle alternatives and adjustable long-press timing; +- battle pause and speed controls that never remove event information; +- remappable keyboard/controller actions and a complete touch path; +- screen-reader labels and deterministic focus order for menus; battle events + have a text event log and pauseable inspection path; +- no required rapid taps, simultaneous multi-touch, precision drag, or audio- + only timing cue; +- low-power mode limiting particles and animation sampling without changing + authoritative simulation or decision windows. + +### 12.2 Input Semantics + +Every platform maps to the same verbs: focus, inspect, compare, move, equip, +confirm, cancel, pause, change speed, select directive, target directive, and +open event log. Dragging is optional convenience; tap-select/tap-destination +must perform every drag action. Destructive or resource-spending actions use a +review state and explicit confirm. Repeating the confirm cannot apply twice. + +Touch targets are at least 48x48 logical pixels with 8 logical pixels between +unrelated destructive actions. Hover information has tap/focus equivalents. +Controller focus never enters the battle scene as an invisible cursor. + +### 12.3 Localization Rules + +- English and Simplified Chinese share semantic message IDs and state tokens. +- No sentence is assembled by concatenating translated fragments. +- Variables use typed placeholders with localized number and plural rules. +- System nouns have one glossary entry; content may not create synonyms for + `Strain`, `Supplies`, `Anchor`, `Directive`, or `Unsecured Cache` casually. +- Layout validation covers English and pseudolocalization at 130% expansion, + and real Simplified Chinese at 130% UI scale. +- Combat abbreviations require expanded accessible names and cannot be the only + way a rule is taught. +- Player-entered names are Unicode-safe, profanity handling is local, and no + generated name is required because all recruits are authored. + +## 13. Content Interface And No-Filler Rule + +Every content row consumed by this product must declare: + +```text +stable_id +localized_name_id +content_type and progression placement +mechanical purpose +state inputs read +authoritative outputs changed +at least two interactions +counter or opportunity cost +presentation silhouette/event requirements +asset, animation, VFX, SFX, and text needs +accessibility communication +validation scenario and expected observable result +``` + +An item is behavior-changing only if it alters at least one of: legal action, +target selection, timing, formation relationship, resource conversion, status +rule, skill execution, route option, risk exposure, or profession identity. A +conditional percent bonus with no changed decision does not qualify. + +An enemy identity must create a distinct preview-to-counter question. A +profession identity must have a distinct target/timing/resource/formation job. +A chapter must combine mechanics in a new way and leave a persistent change. +Rows that differ only by name, art, element color, or scalar fail the package. + +## 14. Product Validation Gates + +### 14.1 Prototype Comprehension + +With at least five uncoached target players: + +- at least four state the next objective within three minutes; +- at least four correctly identify a front/rear protection relation; +- at least four explain why one visible threat changes their preparation; +- at least four can state what is lost or retained before committing risk; +- at least three voluntarily begin another expedition or can name a specific + build they want to test. + +### 14.2 Decision Quality + +- The first meaningful preparation change occurs within three minutes. +- The first visible build interaction occurs within eight minutes. +- The first secure-versus-press decision occurs within twelve minutes. +- A representative 20-minute session contains at least six state-dependent + decisions, excluding confirmations and menu navigation. +- At least two builds clear the same fixed encounter, and each is superior + against a different follow-up threat. +- A single equipment or slot counterfactual changes an observable event in at + least two fixed encounters. +- No profile experiences more than 180 seconds without a meaningful decision. + +### 14.3 Battle Trust + +- Players can name the earliest lane collapse and its cause after the report. +- Every unexecuted command and invalid directive has one specific logged reason. +- 1x shows every major cast, control, downing, rescue, and directive clearly. +- 4x preserves turning points in the event log and never shortens input windows + in simulation time. +- Replaying from the same state, seed, and command timestamps produces the same + authoritative outcome. + +### 14.4 Open Human Gates + +All comprehension targets above are requirements for later tests, not machine- +granted acceptance. Human fun, visual quality, listening quality, tactile +quality, willingness to continue, physical-device behavior, packaging, and +release remain open until the appropriate Owner or device evidence exists. + +## 15. Design Questions Deliberately Closed + +| Question | Decision | +|---|---| +| Is combat fully manual? | No. Loadouts and formation automate actions; at most two directives add timed agency. | +| Can characters permanently die in the first campaign? | No. Defeat causes route loss and temporary Strain, not deletion. | +| Is profession determined by weapon? | No. Profession is learned progression; equipment modifies execution. | +| Can a player buy or grind around a threat? | They can broaden options, but baseline balance assumes no mandatory grind and difficulty never sells power. | +| Does closing the game generate progress? | No. Offline gameplay progression is exactly zero. | +| Is postgame only endless scaling? | No. It has finite mastery, collection, and high-difficulty completion states. | +| Are routine fights always manual? | No. Mastered standing orders may automate declared labor, while new rules retain strategic decisions. | +| Does a stronger item automatically replace a weaker one? | No. Behavior, timing, tags, and formation can make a lower-tier item correct. | +| Can presentation hide exact mechanics for drama? | Never when the mechanic affects a decision or failure. | + +## 16. Acceptance Checklist + +- [ ] Product fantasy is recognizable without reference-game context. +- [ ] Every system contributes to preparation, diagnosis, risk, transformation, + or a different next cycle. +- [ ] The fixed 30/12/24/100/8/320 envelope remains unchanged. +- [ ] Manual, automated, bottleneck, choice, mastery, and transformation stages + are all represented. +- [ ] First campaign, build completion, and collection targets are simulated. +- [ ] Premium, offline, accessibility, localization, and input boundaries are + represented in screen/prototype specifications. +- [ ] Content rows conform to the no-filler schema. +- [ ] Human and release gates remain explicitly open. diff --git a/docs/product/SAVE_AND_FAILURE_CONTRACT.md b/docs/product/SAVE_AND_FAILURE_CONTRACT.md new file mode 100644 index 00000000..1ca16ff8 --- /dev/null +++ b/docs/product/SAVE_AND_FAILURE_CONTRACT.md @@ -0,0 +1,532 @@ +# Aetherbound Guild: Save And Failure Contract + +> Authority: persistence boundaries, transaction idempotency, interruption, +> backup, migration, corruption handling, duplicate protection, clock behavior, +> defeat consequences, and deterministic recovery. +> +> Revision: design-batch-01 / 2026-08-10 +> +> [GAME_PRODUCT_CONTRACT.md](GAME_PRODUCT_CONTRACT.md) owns the player promise. +> [SYSTEMS_AND_BATTLE.md](SYSTEMS_AND_BATTLE.md) owns encounter rules. +> [ECONOMY_AND_BALANCE.md](ECONOMY_AND_BALANCE.md) owns the value and multiplier +> formulas used here. This document has priority whenever a result is ambiguous +> because preserving an authoritative committed state is more important than a +> presentation sequence. + +## 1. Persistence Invariants + +1. A confirmed action is applied exactly once or not at all. There is no state + in which its cost is applied without its declared result. +2. Closing, suspending, crashing, losing power, changing devices, or retrying a + request cannot duplicate a reward, consume a second resource, reroll a route, + or change a deterministic battle outcome. +3. The latest valid local commit remains playable offline. Cloud and platform + services are optional copies, never gameplay authority. +4. Offline gameplay progress is exactly zero. There are no real-time rewards, + construction clocks, energy recovery, expedition simulation, or daily claims. +5. A first-campaign defeat can lose route opportunity and Unsecured Cache value, + and can add Strain, but cannot delete a named adventurer, a banked item, a + profession unlock, Mastery, Anchor restoration, or the save slot. +6. Migration is copy-first and reversible. A new build never rewrites the only + known-valid save. +7. Recovery is deterministic and inspectable. When data cannot be trusted, the + game restores the newest valid backup and identifies the discarded boundary. +8. Save, delete, overwrite, import, cloud-conflict, and risky recovery actions + are fully operable by touch, mouse, keyboard, and controller and are never + color-only or hold-only. + +## 2. Save Topology And Envelope + +The product supports three independent campaign slots. Each slot has one active +commit, three rotating safe backups, one latest Anchor checkpoint, one optional +pre-migration copy, and a bounded operation journal. + +```text +profile_save + profile_schema_version + settings_revision, language, accessibility, input mappings + slot_index[] + platform_entitlement_cache (non-authoritative) + +campaign_slot + slot_id, campaign_id, lineage_id + save_schema_version, ruleset_version, content_revision + commit_id, parent_commit_id, commit_sequence + created_at_wall_clock, last_seen_wall_clock (display only) + deterministic_generation_root_seed + difficulty_contract, selected_reweave_laws + campaign_state, guild_state, roster_state, inventory_state + expedition_state or null + encounter_state or null + operation_journal, achievement_outbox + payload_sha256, envelope_crc32 +``` + +`campaign_id`, `lineage_id`, operation IDs, stable content IDs, and seeds are +128-bit values rendered as lowercase hexadecimal. `commit_sequence` is a local +monotonic unsigned integer. Wall-clock fields are never used to resolve game +rules or conflict winners. + +The envelope has two integrity checks: CRC32 catches incomplete media writes; +SHA-256 covers the canonical payload and catches any other unexpected change. +Neither is treated as anti-cheat or security. The game must not refuse an +offline save because it lacks a server signature. + +## 3. Versioning And Compatibility + +`save_schema_version`, `ruleset_version`, and `content_revision` serve different +purposes: + +| Field | Changes when | Compatibility rule | +|---|---|---| +| `save_schema_version` | Field layout or serialization changes | Requires an ordered migration step | +| `ruleset_version` | Formula, targeting, economy, or failure behavior changes | Existing encounters resume under their stored ruleset until a safe boundary | +| `content_revision` | Stable content rows or localized resources change | Stable IDs must resolve or enter legacy recovery | + +A battle or encounter transaction always finishes under the stored +`ruleset_version`. A newer ruleset becomes active only at the Guild or after an +Anchor commit, before a new route node is generated. The migration UI states +that the next expedition uses revised rules; it never changes a battle already +in progress. + +Supported compatibility is current schema plus the previous three shipped +schemas. Older saves may still be migrated by a tested chain, but lack of such a +chain is a blocking error with an export option, not permission to reset. + +## 4. Transaction And Operation Model + +### 4.1 Operation Identity + +Every state-changing player or system action has a stable `operation_id` scoped +to the campaign: + +```text +operation_id = hash(campaign_id, commit_sequence_at_intent, + operation_kind, source_stable_id, local_nonce) +``` + +The operation journal stores: + +```text +operation_id, operation_kind, intent_hash +status: pending | applied | rejected +pre_commit_id, result_commit_id +cost_delta, result_delta, rejection_reason +created_tick or route_sequence +``` + +The same `operation_id` with the same `intent_hash` returns the stored result. +The same ID with a different intent is rejected as `operation_id_conflict` and +applies nothing. Journal entries remain until two later Anchor checkpoints and +then compact into an immutable applied-ID set. The applied-ID set is retained +for the entire campaign slot. + +### 4.2 Atomic Commit Procedure + +Every transaction follows this order: + +1. Validate the current commit, legal state, cost, target, and intent hash. +2. If the operation is already applied, return its recorded result. +3. Build the complete next payload in memory; do not mutate the active payload. +4. Add the pending operation and all cost/result deltas to that payload. +5. Validate schema, content references, resource non-negativity, item ownership, + roster uniqueness, route ancestry, and encounter hash. +6. Serialize to a new file, write checksum, flush file and containing directory, + then atomically replace the active pointer. +7. Mark the operation applied in the same new commit or an immediate child + commit. On recovery, a `pending` operation with an applied delta is finalized; + one without a complete delta is discarded. +8. Rotate backups only after the new active commit reads back and validates. + +An animation, sound, platform achievement, or cloud upload occurs after step 8. +It cannot determine whether the operation succeeded. + +### 4.3 Transaction Boundaries + +| Action | Commit point | Duplicate response | +|---|---|---| +| Equip/move/change loadout | Confirmed legal state at Guild/Prepare | Return already-equipped result | +| Buy/recruit/craft/upgrade/salvage | Cost and result commit together | Return receipt; do not spend again | +| Reveal/choose route node | Node seed and choice commit before transition | Reopen identical preview/node | +| Start encounter | Initial encounter snapshot and combat seed commit | Resume same countdown | +| Fire Directive | Accepted target and simulation tick commit | One charge and one event only | +| End encounter | Objective outcome and report commit | Reopen same report | +| Claim reward | Chosen stable ID and Cache delta commit | Return same claimed card | +| Secure Cache/Anchor | Cache removal and banked ledger commit together | Return same bank receipt | +| Change difficulty/Reweave law | Guild-only confirmed commit | Reopen selected contract | + +## 5. Encounter Lifecycle And Save Points + +The encounter state machine is: + +```text +preview -> prepared -> committed -> countdown -> resolving + -> outcome_locked -> report -> reward_pending -> reward_applied + -> route_committed +``` + +- `preview`: leaving changes nothing. The preview seed and visible choices are + already stored, so reopening cannot reroll them. +- `prepared`: loadout edits are saved, but the encounter may still be cancelled. +- `committed`: battle seed, company snapshot, difficulty, and failure exposure + are fixed. No equipment/profession edits are accepted. +- `resolving`: deterministic snapshots and a command journal support resume. +- `outcome_locked`: victory, defeat, or retreat predicate is immutable. +- `report`: presentation may be skipped without changing rewards. +- `reward_pending`: cards are fixed; no reward is owned yet. +- `reward_applied`: the chosen reward exists once in the Unsecured Cache or bank. +- `route_committed`: the next route state owns the result; encounter detail may + be compacted after the next Anchor backup. + +Safe save points occur after every confirmed Guild action, route-node reveal, +node commit, accepted Directive, outcome lock, reward claim, Cache operation, +and Anchor restoration. The game also writes a battle resume snapshot every ten +simulation ticks (one simulation second). These snapshots are bounded to the +current encounter and are not exposed as manual save-scumming slots. + +`Save and Quit` completes the current batch and writes the same active commit; +it does not create a branch, reroll point, or separate manual-save lineage. + +## 6. Battle Interruption And Deterministic Resume + +An encounter resume snapshot stores: + +```text +encounter_instance_id, ruleset_version, content_revision +root combat seed and per-stream draw indices +simulation_tick, fixed-point unit state, slots, statuses, threat +event queue, cooldowns, readiness, Aether, Command state +objective/phase state, Fracture Clock +accepted command journal through simulation_tick +snapshot_hash, previous_snapshot_hash +``` + +On normal suspend, the game completes the current 0.1-second batch, writes a +snapshot, then acknowledges suspend. If the process is killed first, recovery +loads the newest valid snapshot and replays accepted commands from the previous +valid snapshot. Replayed commands carry their original ticks and operation IDs. + +Recovery never substitutes current wall-clock time. A battle suspended for a +week resumes at the same simulation tick and next event. Display interpolation, +camera, particles, and non-authoritative audio restart from the recovered state. + +If the latest snapshot is corrupt: + +1. validate snapshots newest to oldest; +2. load the newest valid snapshot with a matching encounter and ruleset; +3. replay journaled commands and deterministic streams to the last committed + tick; +4. compare the reconstructed state hash with the stored checkpoint hash; +5. if it matches, resume and record `snapshot_recovered`; +6. if no snapshot matches, roll back to `committed` and restart the identical + encounter seed with the same loadout, automatically replay every valid + journaled command at its original tick, and resume after the last such tick + with no cost/reward changes. + +Restarting from `committed` is a recovery action, not a player-selectable retry. +It is unavailable after an outcome has been locked. + +## 7. Duplicate Action And Reward Protection + +### 7.1 Input Debounce Is Not Authority + +UI debounce may prevent repeated taps, but correctness relies on operation IDs. +Touch double-taps, controller repeat, network retry, OS lifecycle replay, and +cloud reconciliation all return the first committed result. + +For a Directive: + +```text +accept(command_id, target, tick): + if command_id in applied_ids: return stored_result + if charge < 1 or target illegal: reject without cost + otherwise spend 1 charge and enqueue exactly one command at tick+1 +``` + +For a reward claim: + +```text +claim(reward_operation_id, card_id, disposition): + verify card_id belongs to fixed draft + verify operation has no applied result + remove draft, add exactly one Cache/bank entry, append applied ID + commit all fields atomically +``` + +No inventory repair routine may create a second item to compensate for a +display problem. It first resolves ownership from the operation journal. + +### 7.2 Achievement And Platform Outbox + +Achievements are derived from committed gameplay facts. When offline, up to 100 +idempotent platform events are queued. If the bound is reached, older events are +re-derived from campaign facts later; gameplay never blocks and no reward is +lost. Platform success or failure cannot modify Crowns, items, XP, Mastery, +route state, or completion state. + +## 8. Backup, Corruption, And Recovery + +### 8.1 Backup Rotation + +Each campaign slot keeps: + +- `active`: newest fully validated commit; +- `backup_1..3`: three prior safe commits at distinct transaction boundaries; +- `anchor_checkpoint`: latest valid Anchor commit, retained until a newer Anchor; +- `pre_migration`: original file before a schema/ruleset migration; +- `quarantine`: corrupt bytes and a diagnostic manifest, never auto-deleted. + +Backups are written only inside the slot's explicit storage directory. A failed +rotation leaves the active file and previous backups untouched. Storage pressure +first removes old diagnostic logs, never the active or latest Anchor backup. + +### 8.2 Validation Order + +On load, validate in this order: + +1. envelope parse and size bounds; +2. CRC32 and SHA-256; +3. schema and required fields; +4. campaign/lineage/parent commit relationships; +5. resource bounds and nonnegative balances; +6. stable content IDs and item ownership uniqueness; +7. roster and profession topology; +8. expedition route ancestry and committed node; +9. encounter snapshot and operation-journal consistency. + +A presentation preference error falls back to defaults without touching the +campaign. A gameplay-state error invokes backup recovery. The game never labels +a save corrupt merely because optional cloud or platform services are offline. + +### 8.3 Recovery Result + +When recovery selects a backup, the player sees: + +- which slot was affected; +- the recovered boundary (`Guild`, `Anchor`, `node`, `battle snapshot`, or + `report`); +- the number and kinds of operations after that boundary that could not be + verified; +- options to continue from the recovered state, inspect technical details, or + export a diagnostic copy; +- an explicit statement that the quarantined file was preserved. + +The default focus is `Continue recovered save`, not delete or overwrite. A +recovery message may not claim that all progress was preserved unless the +active and reconstructed commit hashes match. + +## 9. Migration Contract + +Migration runs only at startup or the Guild, never during an expedition or +encounter. The procedure is: + +1. Validate and preserve the original as `pre_migration`. +2. Build a migration plan of adjacent version steps; skipping a step is illegal. +3. Resolve stable content-ID mappings and list any legacy rows. +4. Apply each pure migration function to a copy. +5. Validate every invariant and recompute derived values from source fields. +6. Write a new lineage child commit with migration IDs and old/new hashes. +7. Read back, then switch the active pointer. Preserve the old copy until two + valid Anchor commits under the new version. + +Migrations never generate random values. If a removed item ID has no direct +replacement, it becomes a `legacy_sealed_item` retaining original stable ID, +band, tier, and salvage value. It cannot be equipped; at the Guild, the player +chooses one of two deterministic same-band replacements or keeps it sealed for +a future migration. There is no silent auto-equip or value loss. + +If any step fails, the new copy is discarded, the original remains active under +its last supported ruleset when possible, and the slot is marked +`migration_blocked`. Other slots and settings remain usable. + +## 10. Local, Cloud, And Multi-Device Conflict + +Cloud is an optional transport of complete validated commits. It does not merge +inventories, rewards, route nodes, or operation journals. A cloud upload carries +`campaign_id`, `lineage_id`, `commit_id`, `parent_commit_id`, and sequence. + +| Relationship | Resolution | +|---|---| +| Same commit | No action | +| Local is ancestor of cloud | Offer cloud as newer; retain local backup | +| Cloud is ancestor of local | Keep local; queue upload | +| Different lineage/campaign | Offer to import cloud into an empty/duplicated slot | +| Same lineage, divergent descendants | Never auto-merge; show both boundaries and require keep local, keep cloud, or duplicate one | + +Conflict choices use commit boundary, chapter, play duration, Anchor, and last +known objective. Wall-clock `newer` is display context only. The default is +`Cancel and inspect`, and no option deletes the unchosen copy until the selected +copy has been validated and backed up. + +## 11. Clock Rollback And Offline Behavior + +All gameplay clocks are simulation ticks or monotonic session duration. Wall +clock is used only for human-readable save dates and diagnostics. + +On startup: + +```text +wall_delta = current_wall_clock - last_seen_wall_clock +if wall_delta < -300 seconds or wall_delta > 180 days: + record clock_anomaly for diagnostics + do not change gameplay state or deny play +``` + +Changing the device clock cannot grant or remove Crowns, Supplies, shop offers, +route nodes, XP, Mastery, unlocks, or platform achievements. A queued platform +event with a timestamp outside service limits remains derived from committed +facts and is retried without a gameplay reward. + +While the game is closed, expedition and encounter time advances by exactly +zero ticks. On return, the player receives a compact recap of the saved state, +not an offline income panel. Optional platform uploads are bounded background +work and stop cleanly without blocking local commits. + +## 12. Failure State Model + +Failure is classified before consequences are calculated: + +| Failure kind | Predicate | Earliest committed boundary | Outcome | +|---|---|---|---| +| Encounter defeat | All deployed units Lost/Downed with no legal rescue, objective fails, or Fracture reaches 180 s | `outcome_locked` | Apply difficulty defeat transaction | +| Voluntary battle retreat | Three-second retreat channel completes after its legal time | `outcome_locked` | Apply retreat transaction | +| Route withdrawal | Player confirms at noncombat node | Route commit | Bank declared fraction, end expedition | +| Hazard failure | Authored visible condition fails | Node result | Apply declared Supply/Strain/Cache delta once | +| Invalid action | State/target/cost precondition fails | No commit | Spend nothing; return one reason | +| Process interruption | App is suspended/killed/crashes | Last valid save point | Resume/reconstruct; not a gameplay failure | +| Save corruption | Active commit fails validation | Last valid backup | Recover/quarantine; not a gameplay failure | + +## 13. Defeat, Retreat, Strain, And Cache Consequences + +### 13.1 Cache Loss Algorithm + +Every Unsecured Cache line stores `cache_line_id`, stable reward ID, quantity, +`risk_value`, and acceptance sequence. Before node commitment, the preview shows +the exact loss set for the active difficulty. + +For loss fraction `P`: + +```text +loss_target = floor(total_cache_risk_value * P) +order cache lines by acceptance_sequence descending, then cache_line_id +remove/split lines until removed risk value >= loss_target +never remove a banked line or more than the Unsecured Cache owns +``` + +Crowns and stackable materials may split exactly. An indivisible item that would +overshoot remains in the Cache and the algorithm continues to the next line; +if no line can satisfy the remainder, the actual loss is smaller and is shown. +There is no random loss roll. + +### 13.2 Difficulty Transactions + +| Contract | Defeat | Battle retreat | Noncombat withdrawal | +|---|---|---|---| +| Wayfinder | Lose 25% Cache, consume up to 1 Supply, +1 Strain to each Downed/Lost unit (at most two affected units) | Lose 15% Cache, consume 1 Supply, +1 Strain to units Lost before channel | Bank 75% Cache, discard remainder, end expedition | +| Stormbound | Lose 50% Cache, consume up to 2 Supplies, +1 Strain to every Downed/Lost deployed unit | Lose 30% Cache, consume 2 Supplies, +1 Strain to Lost units | Bank 50% Cache, discard remainder, end expedition | +| Iron Oath | Lose 100% Cache, consume all Supplies, +2 Strain to Lost units, close current route | Lose 60% Cache, consume all but 1 Supply, +1 Strain to all deployed units | Bank 25% Cache, discard remainder, end expedition | + +After the transaction, if at least one Supply remains and at least one deployed +or reserve adventurer has fewer than three Strain, the party returns to the last +Anchor with the revealed graph intact except where Iron Oath closes the current +route. Otherwise the expedition ends at the Guild. Banked state, chapter +restorations, roster, inventory, XP, and Mastery remain intact. + +For a noncombat withdrawal, resolve the Cache bank/discard fraction first, then +apply the unused-Supplies Crown conversion from the economy authority in the +same expedition-close operation. Defeat never receives that conversion. + +On victory, an adventurer whose Rescue Window expired gains one Strain as stated +in the systems authority. A rescued adventurer gains none from that Downed event. +Strain caps at three; overflow is discarded and logged. At three Strain the +adventurer cannot deploy but can still be inspected, respeced, equipped, and +recovered. One Supply at a Camp/Anchor clears one Strain from one adventurer; +returning to the Guild clears all Strain without cost and ends the expedition. + +### 13.3 Recovery Choice + +The Recovery state shows: + +1. outcome cause and first preventable event; +2. exact Cache lines lost, banked, and retained; +3. each adventurer's Strain before/after; +4. Supplies before/after and route position; +5. three legal next actions: reconfigure at Anchor, train against the same seed + with no reward, or end the expedition at the Guild. + +It never offers a paid continue, random reroll, automatic best-loadout button, +or destructive character replacement. The same-seed training replay is not a +rollback: it is a separate no-reward simulation whose result cannot alter the +committed failure. + +## 14. Confirmation, Delete, And Reset Boundaries + +The following actions require a review state with exact effects, then a separate +confirm input: difficulty increase, Reweave-law activation, route withdrawal, +Cache discard, salvage of an unlocked item, cloud conflict resolution, migration +fallback, campaign-slot overwrite, and campaign-slot delete. + +Deleting a campaign slot requires selecting the exact slot name and confirming +again after the summary. The active save moves to a recoverable local trash area +for seven successful launches or until the player explicitly empties it. A +profile-wide reset additionally requires entering a displayed localized phrase; +controller and touch users can select the phrase from a two-step dialog rather +than type it. No cancel/default focus may point at delete. + +An accepted confirm receives an operation ID. Repeating the input returns the +first result and cannot delete or spend twice. + +## 15. Accessibility, Localization, And Input Requirements + +- Save state is communicated by text and icon, never only color or a spinning + indicator. `Saving`, `Saved`, `Recovered`, `Conflict`, and `Blocked` have + distinct accessible labels. +- Closing during `Saving` is legal; the previous active commit remains valid. +- Every recovery/conflict dialog supports 130% UI scale, screen-reader order, + keyboard/controller focus, and a complete tap-select path. +- Technical IDs are hidden by default but available in an inspectable details + panel and copyable/exportable diagnostic manifest. +- Localized messages use semantic IDs and typed values. They never concatenate + amounts, item names, operation kinds, or recovery boundaries into fragments. +- Numeric loss previews use localized formatting and also list affected cache + rows, so a percentage is not the only explanation. +- Haptics and audio may confirm a commit but cannot be the only saved/failed cue. +- A controller disconnect, focus loss, or input-device change pauses target + selection and spends nothing until a new confirm is accepted. + +## 16. Required Recovery And Failure Test Matrix + +| Test | Interruption/fault point | Expected invariant | +|---|---|---| +| Equip commit | After cost validation, before atomic pointer switch | Old loadout or complete new loadout; never partial | +| Purchase duplicate | Same operation ID delivered twice | One cost and one item | +| Directive duplicate | Same command ID at same tick twice | One charge and one event | +| Battle suspend | During cast at tick 417 | Resume at tick 417 boundary; identical final hash | +| Battle crash | After snapshot write, before pointer update | Use prior valid snapshot and journal; identical final hash | +| Outcome crash | After victory predicate, before report animation | Reopen same victory report and fixed rewards | +| Reward crash | After card choice, before screen transition | Exactly one Cache/bank line; same card on reload | +| Anchor crash | During Cache banking | Entire Cache banked once or still unsecured; no split duplicate | +| Clock rollback | Device clock moves back 24 hours | Diagnostic only; zero gameplay change | +| Seven-day offline | Close mid-expedition and return | Zero tick/resource progress; recap and resume | +| Active save corrupt | Break checksum | Load newest valid backup, quarantine active, show boundary | +| All battle snapshots corrupt | Valid committed start and command journal remain | Restart identical seed/loadout, replay commands at original ticks, no cost/reward change | +| Migration failure | Invalid stable-ID mapping | Original stays active; new copy discarded; export offered | +| Cloud divergence | Local and cloud share parent but differ | No merge/overwrite; keep/duplicate choice | +| Wayfinder defeat | 200 Cache risk value, two Lost units, 4 Supplies | Lose 50 value, spend 1 Supply, each gets 1 Strain | +| Stormbound withdrawal | 200 Cache at noncombat node | Bank 100 value, discard 100, end expedition | +| Iron Oath defeat | Any positive Cache and Supplies | Lose all Cache/Supplies, route closes, roster remains | + +## 17. Acceptance Checklist + +- [ ] Schema, ruleset, content, lineage, commit, and operation versions are + separated and migration paths are copy-first. +- [ ] Every resource/action/reward transaction is atomic and idempotent. +- [ ] Battle suspension and crash recovery reproduce the authoritative hash. +- [ ] Duplicate input, reward claim, platform retry, and cloud conflict cannot + duplicate or erase gameplay state. +- [ ] Active, backup, Anchor, pre-migration, and quarantine behavior is explicit. +- [ ] Clock rollback and bounded offline behavior create zero gameplay progress. +- [ ] Wayfinder, Stormbound, and Iron Oath failure consequences match the economy + authority and never delete a first-campaign adventurer or banked asset. +- [ ] Recovery, conflict, overwrite, reset, and delete flows meet input, + accessibility, localization, and confirmation requirements. diff --git a/docs/product/SYSTEMS_AND_BATTLE.md b/docs/product/SYSTEMS_AND_BATTLE.md new file mode 100644 index 00000000..3a7b6a3f --- /dev/null +++ b/docs/product/SYSTEMS_AND_BATTLE.md @@ -0,0 +1,930 @@ +# Aetherbound Guild: Systems And Battle Authority + +> Authority: canonical gameplay state, expedition flow, formation, auto-battle, +> professions, skills, equipment hooks, tactical intervention, and diagnostic +> behavior. +> +> Revision: design-batch-01 / 2026-08-10 +> +> Product intent is defined in +> [GAME_PRODUCT_CONTRACT.md](GAME_PRODUCT_CONTRACT.md). Numeric economy and +> pacing are defined in [ECONOMY_AND_BALANCE.md](ECONOMY_AND_BALANCE.md). +> Commit, interruption, defeat, and recovery semantics are defined in +> [SAVE_AND_FAILURE_CONTRACT.md](SAVE_AND_FAILURE_CONTRACT.md). + +## 1. Non-Negotiable System Invariants + +1. The active company contains zero to six deployed adventurers on a fixed + three-lane by two-rank Weave Grid. An expedition may carry up to two reserves. +2. Adventurers do not freely wander away from assigned formation anchors. + Movement, displacement, and slot changes are discrete and explainable. +3. The authoritative simulation advances at fixed 0.1-second ticks. Display + speed and frame rate do not alter outcomes. +4. Normal attacks never miss through hidden random evasion. Avoidance is an + explicit status, charge, block, range, or line rule. +5. Every enemy major action is declared in preview and telegraphed in battle. + Immunity and targeting exceptions are visible before commitment. +6. The player prepares two tactical directives and may spend at most two + Command charges in one encounter. +7. The same start state, content revision, seed, and tick-stamped player + commands produce the same authoritative result. +8. Every rejected or unexecuted action has exactly one machine-readable reason. +9. Combat power cannot grant more than 95% total damage reduction, 60% generic + critical chance, 50% max-HP barrier, or permanent hard control. +10. A normal campaign character can be Downed and gain Strain but is not + permanently deleted. + +## 2. Authoritative State Model + +```text +profile + settings, accessibility, language, input mappings + entitlements and platform-service cache (never gameplay authority) + +campaign slot + campaign_id, ruleset_version, difficulty + chapter/anchor/world transformations + guild rank, roster, learned professions, mastery + inventory, currencies, catalog, achievements + deterministic generation root seed + +expedition + expedition_id, chapter, route seed and revealed graph + deployed company and reserves + supplies, strain snapshot, unsecured cache + current anchor, committed node, standing order + +encounter transaction + encounter_instance_id, phase, combat seed + Weave Grid, units, stats, cooldowns, statuses, threat + event queue, tick, directives, Command state + outcome and idempotent reward operation IDs + +presentation only + camera, animation interpolation, particles, selected panel, + expanded tooltip, pointer position, non-authoritative sound state +``` + +Presentation may interpolate but may never author damage, movement, targeting, +reward, timing, or save state. All numeric combat calculations use integer +fixed-point values at 1/100 precision and round only at the boundaries stated +below. + +## 3. Weave Grid Geometry + +### 3.1 Slots + +All standard encounters use six allied and six enemy anchors: + +```text +ALLIED ENEMY + +R1 ---- F1 EF1 ---- ER1 +R2 ---- F2 EF2 ---- ER2 +R3 ---- F3 EF3 ---- ER3 + +R = rear rank, F = front rank +``` + +The screen may render depth and hand-drawn motion, but these slot IDs remain +authoritative. Slot adjacency is orthogonal: + +- same-rank neighboring lanes: `F1-F2`, `F2-F3`, `R1-R2`, `R2-R3`; +- same-lane front/rear links: `F1-R1`, `F2-R2`, `F3-R3`; +- diagonals are not adjacent unless a skill explicitly declares diagonal reach; +- lane distance is `abs(source_lane - target_lane)`; +- rank distance is zero within a rank and one across ranks. + +Large enemies may occupy two declared adjacent enemy slots. They have one unit +ID, one health pool, and a primary slot for tie-breaking. A large unit must +declare which occupied lanes it threatens. No content may visually occupy +multiple slots while mechanically using only an undisclosed one. + +### 3.2 Front Protection + +A living, non-Downed front unit protects the rear unit in the same lane unless +the protector has `Broken`, is displaced out of the link, or the incoming skill +has `bypass_front`. Protection has three effects: + +1. standard melee cannot target the protected rear unit; +2. standard ranged attacks against that rear unit receive `-120` Target Score; +3. `interceptable` attacks transfer 50% of post-mitigation damage to the front + protector before barrier absorption; the attack preview shows this split. + +The transfer percentage can be modified only by an explicit skill or item and +is clamped to 0%-80%. Transfer cannot recursively trigger another intercept. +If no rear unit exists, the front unit still holds the lane but gains no hidden +bonus. + +### 3.3 Displacement And Slot Changes + +Movement is a transaction between slots, not free pathfinding: + +- `shift`: move to an empty orthogonally adjacent allied slot; +- `swap`: exchange two living allied units in adjacent slots; +- `push`: move target one rank away from source, then one lane away according + to the skill's declared direction if rank movement is impossible; +- `pull`: reverse of push; +- `invade`: an enemy-only declared move into an empty allied front slot; +- `return`: move an invader to its stored enemy anchor when the effect ends. + +If a forced destination is occupied or outside the grid, movement fails and +the target takes `Stagger = 10 + 0.10 * source Physical Power` before defense. +Forced movement cannot chain more than once per tick. `Anchored` rejects forced +movement but not voluntary swap. Every rejection logs `ANCHORED`, `OCCUPIED`, +`OUT_OF_GRID`, `DOWNED`, `ROOTED`, or `CAST_LOCK`. + +## 4. Encounter Lifecycle + +| Phase | Legal player/system actions | Commit boundary | +|---|---|---| +| Preview | Inspect threats, rewards, objective, Fracture Clock, enemy slots | No cost; generated preview is stable | +| Prepare | Deploy, equip, set skills/AI priorities, select two directives | Confirm creates immutable pre-battle snapshot | +| Countdown | Three simulation seconds; inspect and pause allowed | Formation changes locked | +| Resolve | Auto actions and up to two directives | Tick-stamped events journaled | +| Outcome locked | Victory, defeat, retreat, or scripted objective result | Combat state cannot be changed | +| Diagnose | Compare predicted/actual targets, causes, contribution | No reward applied by viewing/skipping | +| Reward review | Choose reward and cache disposition | Choice has one operation ID | +| Finalized | Apply result once and return to route/recovery | Encounter transaction archived | + +Leaving the preview never rerolls it. Leaving preparation after confirmation +returns to the same immutable snapshot and requires explicit cancel to abandon +the committed node. Save rules for each phase are in the save authority. + +## 5. Unit Statistics + +### 5.1 Primary Attributes + +Every adventurer has five nonnegative integer attributes. Enemy data may define +equivalent derived values directly. + +| Attribute | Primary role | Does not do | +|---|---|---| +| Might | Physical Power, physical Guard contribution | Determine profession or hidden carry weight | +| Finesse | Tempo, critical precision, initiative | Grant passive random dodge | +| Insight | Arcane Power, status Potency | Bypass visible Ward rules | +| Vigor | Max HP, Guard, stagger resistance | Create automatic regeneration | +| Resolve | Ward, healing contribution, status Tenacity | Make a unit silently control-immune | + +Character bases, level growth, profession modifiers, and equipment bonuses are +summed before derived calculations. A primary attribute is clamped to 0-250 in +the first campaign and 0-400 in Reweave. Values outside the cap are shown as +overflow and do not affect combat. + +### 5.2 Derived Statistics + +For level `L` (1-50 first campaign; postgame cap 70), use: + +```text +PhysicalPower = WeaponPower + 2.00*Might + 0.60*Finesse +ArcanePower = FocusPower + 2.00*Insight + 0.60*Resolve +HealingPower = FocusPower + 1.30*Insight + 1.30*Resolve +MaxHP = JobBaseHP + 12*L + 10*Vigor +Guard = ArmorGuard + 1.25*Vigor + 0.75*Might +Ward = ArmorWard + 1.25*Resolve + 0.75*Insight +Potency = Insight + 0.50*Finesse + flat_potency +Tenacity = Resolve + 0.50*Vigor + flat_tenacity +Tempo = clamp(JobBaseTempo * (1 + Finesse/(Finesse+250)) + + flat_tempo, 20, 100) +Initiative = clamp(JobBaseInitiative + 0.25*Finesse + + flat_initiative, 0, 95) +``` + +`WeaponPower`, `FocusPower`, `ArmorGuard`, and `ArmorWard` are generic budget +terms; an item may supply more than one. Jobs define `JobBaseHP` in 180-420, +`JobBaseTempo` in 25-50, and `JobBaseInitiative` in 0-50. Content outside these +ranges needs a documented system exception and a fixed validation encounter. + +Derived values are calculated at battle start and on explicit stat changes. +Max HP changes preserve current HP percentage, rounded down, unless an effect +states that it heals. No equipment swap is legal during Resolve. + +## 6. Deterministic Time, Events, And Randomness + +### 6.1 Fixed Tick + +The simulation tick is exactly 100 milliseconds. Display frames sample the +latest completed state. At each tick, event priorities are: + +1. lifecycle commands (pause/resume/retreat) and accepted player directives; +2. status expiry, periodic effects, and resource drains; +3. cast/channel completions; +4. ready automatic actions; +5. movement and displacement; +6. simultaneous damage/heal/barrier application within each priority batch; +7. Downed, objective, phase-transition, and Command-gain checks; +8. readiness, cooldown, duration, and telegraph clocks advance. + +Events at the same priority read the same pre-batch state and apply their +numeric outputs together. A unit alive at the start of a simultaneous batch +completes its already-scheduled event even if that batch Downs it. Ties use +stable unit ID only for nonnumeric presentation order and conflicting movement; +combat totals do not gain an ID-order advantage. + +### 6.2 Seeded Random Streams + +Each encounter stores a 128-bit root seed and separate labeled streams: + +```text +target_tie, critical, status_apply, reward, route_event +``` + +Adding a reward draw must not shift combat draws. Draws include stream name, +event sequence, and content stable ID in the journal. There is no damage +variance. Random outcomes are limited to declared critical checks, declared +status application below 100%, equal-score target ties, and generated content +choices. Preview shows the bounded chance or deterministic outcome. + +## 7. Readiness, Skills, And Action Timing + +Each unit has Readiness from 0-99.99. At battle start it equals Initiative. +Each tick: + +```text +Readiness += Tempo * 0.1 +``` + +At `Readiness >= 100`, AI selects one legal action. The selected action reserves +its target, subtracts 100 Readiness, and begins its wind-up/cast. Any overflow +is retained, capped at 50. If no action is legal, the unit waits one tick and +does not spend Readiness. + +| Timing field | Boundary | +|---|---| +| Wind-up | 0.1-1.5 s; interruptible only if tagged | +| Cast/channel | 0.5-4.0 s; major casts require telegraph contract | +| Recovery | 0-2.0 s during which Readiness can fill but no action starts | +| Cooldown | 0-30 s, advanced every simulation tick | +| Global lock | At most 0.3 s and only for preventing duplicate starts | + +Auto AI evaluates actions in the player-authored four-row priority list, then +uses the fixed basic action. Each priority row contains `skill`, `condition`, +and `target policy`. Conditions may read only currently visible authoritative +state: HP bands, barrier, status, lane, protected/exposed, ally count, enemy +count, cast tag, phase, Aether, and cooldown. They may not inspect future RNG. + +## 8. Targeting, Threat, And Aggro + +### 8.1 Candidate Filter + +An action first constructs legal candidates from its row data: + +- side: ally, enemy, self, slot, or all; +- reach: same lane, adjacent lane, any lane, front, rear, or occupied slots; +- protection: obey front, ranged penalty, bypass front, or interceptable; +- state: living, Downed, damaged, cast-active, status-present, and exclusions; +- maximum targets and deterministic area shape. + +If the reserved target becomes illegal before completion, the skill follows its +declared `retarget`, `fizzle`, or `ground_resolve` policy. This policy appears in +the tooltip. A fizzle refunds 50% of cooldown and all unspent profession +resource unless content explicitly declares a visible nonrefundable wager. + +### 8.2 Threat Meter + +Each unit has Threat `T`, initialized to the profession's `BaseThreat` in +0-100. It changes after effective outcomes: + +```text +damage threat = 40 * effective_damage / target_MaxHP +support threat = 25 * (effective_heal + effective_barrier) / ally_MaxHP +control threat = 12 * effective_control_seconds +``` + +Threat gains are summed per tick, capped at +60 per tick, and decay 5 per +simulation second toward BaseThreat. Overkill, overheal, and wasted barrier add +zero. An effect may add taunt threat explicitly, capped at +300. + +### 8.3 Target Score + +For each legal candidate, standard hostile AI computes: + +```text +TargetScore = T + + lane_affinity + + state_priority + + vulnerability_priority + + focus_priority + - protection_penalty +``` + +Default terms: + +| Term | Score | +|---|---:| +| Same lane | +120 | +| Adjacent lane | +40 | +| Other lane | +0 | +| Target below 30% HP, if action has `finish` | +100 | +| Target currently casting, if action has `disrupt` | +120 | +| Target has required setup tag | +160 | +| Focus Order mark | +1000 | +| Protected rear against ranged | -120 | +| Explicit untargetable/invalid | removed, not a large negative | + +The highest score wins; exact ties use the `target_tie` stream. A forced target +must still be legal and reachable. If a Focus target cannot be selected, the +log names the filter that rejected it rather than silently choosing another. + +Player-facing prediction shows the first expected target before battle and +updates after formation/loadout changes. + +## 9. Damage, Healing, Barrier, And Criticals + +### 9.1 Damage + +Skills declare `Base`, `Coefficient`, `PowerSource`, damage type, pierce, and +tags. Calculate: + +```text +Raw = Base + Coefficient * selected_power +EffectiveDefense = clamp(relevant_defense - pierce, -75, 500) + +if EffectiveDefense >= 0: + DefenseMultiplier = 100 / (100 + EffectiveDefense) +else: + DefenseMultiplier = 2 - 100 / (100 - EffectiveDefense) + +CritChance = clamp(skill_base_crit + + 0.002*(source_Finesse - 0.5*target_Resolve) + + explicit_crit_bonus, + 0, 0.60) + +FinalDamage = floor(max(1, + Raw * DefenseMultiplier * CritMultiplier + * outgoing_group * incoming_group * encounter_group)) +``` + +`relevant_defense` is Guard for physical, Ward for arcane, and zero for true +damage. True damage cannot crit and may not exceed 20% of target Max HP from a +single non-boss event. Base CritMultiplier is 1.50 and is clamped to 1.00-2.25. + +Within each modifier group, bonuses add before the group is multiplied. Each +group is clamped to 0.25-3.00; final outgoing x incoming x encounter is clamped +to 0.10-5.00. Total reduction from all sources cannot reduce a positive hit +below 5% of its pre-defense Raw unless a visible block, immunity, or barrier +absorbs it. + +### 9.2 Healing + +```text +RawHeal = Base + Coefficient * HealingPower +FinalHeal = floor(max(0, + RawHeal * outgoing_heal_group * received_heal_group + * encounter_heal_group)) +EffectiveHeal = min(FinalHeal, MaxHP - current_HP) +``` + +Healing cannot crit unless a skill declares `healing_crit`; its chance uses the +same cap and must be visible. Overheal is discarded unless an explicit effect +converts it. Conversion is capped at 50% of overheal and respects the barrier +cap. + +### 9.3 Barrier And Block + +Barrier absorbs damage after interception and mitigation. Generic barrier on a +unit is capped at 50% Max HP. New barrier adds to the existing amount up to the +cap; oldest timed barrier expires first. Barrier does not increase Threat from +wasted amount. + +`Block` is an explicit charge that negates one eligible hit after interception +but before barrier. Area, true, or `unblockable` damage is ineligible and shown +as such. A unit may hold at most three generic Block charges. + +## 10. Status Effects And Control + +### 10.1 Common Status Schema + +Every status row declares: + +```text +stable_id, category, source_id, target_id +base_apply_chance, potency_source, resist_stat +duration, tick_interval, max_stacks +stack_rule (add/refresh/replace/independent) +dispel_tags, immunity_tags, control_group +on_apply, on_tick, on_expire, presentation events +``` + +Apply chance for a resistible status is: + +```text +ApplyChance = clamp(BaseChance + 0.005*(Potency - Tenacity), 0.10, 0.95) +``` + +`guaranteed` effects bypass the probability roll but not declared immunity. +`unresistable` is reserved for encounter rules, never ordinary item procs. +Stack count, duration, next tick, source, and immunity are inspectable. + +### 10.2 Categories + +| Category | Contract | +|---|---| +| Affliction | Periodic damage or healing reduction; snapshots declared stats at application unless tagged dynamic | +| Impairment | Non-hard debuff to Tempo, power, defense, targeting, or movement | +| Control | Interrupt, Root, Silence, Stun, Sleep, or Fear; subject to control resistance and immunity windows | +| Mark | Enables targeting, setup, or resource interaction; no hidden numeric payload | +| Boon | Positive stat/rule modifier with visible duration | +| Barrier/Block | Damage prevention governed by Section 9.3 | +| Injury | Expedition-persistent Strain only; never dispelled in battle | + +### 10.3 Hard-Control Boundary + +For Stun, Sleep, and Fear: + +```text +EffectiveDuration = clamp(BaseDuration * 100/(100 + Tenacity), 0.25, 4.0) +``` + +Boss/elite data may further cap one application to 1.5/2.5 seconds, but must +show that cap in preview. After hard control ends, the target gains `Control +Guard` for `2 + EffectiveDuration` seconds. During Control Guard, new hard +control duration is reduced 70%; a second consecutive application grants +immunity for four seconds. No unit can be unable to act for more than 50% of +any rolling ten-second window. + +Interrupt is not hard control: it cancels an interruptible cast and applies +the cast's declared recovery. Silence blocks tagged spells but not movement, +basic action, directives, or passive effects. + +## 11. Profession Resources And Skill Loadout + +Every profession uses the shared `Aether` meter from 0-100 for its Signature. +Basic actions gain 8 Aether, techniques gain or spend their declared amount in +-40 to +30, taking effective damage gains at most 10 per tick, and passive gain +is capped at 5 per second. A Signature requires 100 and spends all 100 unless +its row declares a partial-cost advanced rule. No Signature fires automatically +without a player-visible AI condition. + +An active loadout contains exactly: + +- one fixed profession trait; +- one fixed basic action; +- two selected techniques; +- two selected passives; +- one selected Signature; +- a four-row automatic priority list plus basic fallback. + +Each base profession provides one trait, one basic, three techniques, three +passives, and one Signature. Each advanced profession is a branch of exactly +one base and adds one trait transformation, two techniques, two passives, and +one alternate Signature. Advanced loadouts choose from the combined base and +branch pool; they do not gain additional slots. + +This cap prevents advanced professions from being pure action-count upgrades. +Every branch must exchange at least one target, timing, formation, resource, or +risk rule for another; a branch consisting only of larger coefficients fails. + +## 12. The 12 Base And 24 Advanced Profession Contract + +Content names the professions. The system requires this exact topology: + +```text +12 base professions + each base -> branch A + branch B + total advanced professions = 24 +``` + +### 12.1 Required Base Distribution + +Across the 12 bases, primary functions must be distributed exactly: + +| Primary function | Count | Required distinct question | +|---|---:|---| +| Hold/protect | 3 | Which lane or damage window deserves protection? | +| Pressure/finish | 3 | Which target or timing converts setup into defeat? | +| Restore/enable | 3 | Which ally/resource/timing preserves the plan? | +| Control/reposition | 3 | Which enemy action or slot relation must change? | + +Each base also declares one secondary function from a different row. No two +bases may share all of: preferred rank, target policy, Aether loop, damage type, +primary counter tag, and timing profile. + +### 12.2 Branch Pair Rule + +The two branches of one base must answer opposed planning goals. Allowed axes +include single-lane versus cross-lane, prevention versus recovery, burst versus +sustain, setup versus payoff, self-risk versus ally-risk, or fixed formation +versus repositioning. Both must retain the base's recognizable trait. + +For every branch pair, content supplies two fixed counterfactual encounters: + +1. one in which branch A is rationally superior; +2. one in which branch B is rationally superior. + +The losing branch must remain capable of winning with a different company; the +test proves state dependence, not a hard key/lock gate. + +### 12.3 Character Access And Advancement + +- Every recruit begins with one authored base profession. +- Every recruit declares two additional learnable base professions; the three + must include at least two primary-function groups. +- A recruit can learn all three eventually, but has one active profession. +- A base reaches `Adept` at 100 Mastery and `Master` at 300 Mastery. +- Its advanced branches become learnable only after Adept, the branch's + chapter transformation, and one authored mastery trial. +- Both branches can be learned by the same recruit. Only one is active. +- Advanced mastery is tracked per branch; it does not erase base mastery. +- Level is character-wide. Profession mastery unlocks options, not mandatory + permanent stat percentages. + +The content package must distribute access so all 12 bases are available in +the roster by the end of Chapter 3 and all 24 branches by the end of Chapter 8. + +### 12.4 Respec And Switching + +At the Guild, all learned profession switches, skill selections, AI priorities, +and attribute-growth choices are free and reversible. Equipment is never +destroyed by unequipping. + +During an expedition: + +- formation, equipment, skills, and priority rows can change during Prepare; +- active profession/advanced branch can change only at an Anchor; +- the first one-character profession change at each Anchor is free; +- each additional changed character before leaving that Anchor costs one + Supply, disclosed before commit; +- no respec or item swap is legal after battle confirmation. + +Refunding an unlocked skill returns all spendable skill points atomically. +Mastery and story unlocks cannot be refunded because they are non-spend +progress records. + +## 13. Equipment And Item System Hooks + +Each adventurer has four equipment slots: + +| Slot | Baseline role | Boundary | +|---|---|---| +| Focus | Primary attack/cast expression and Power budget | Does not determine profession | +| Garb | HP, Guard, Ward, and protection behavior | Cannot grant more than 25% generic reduction alone | +| Relic | Status, resource, timing, or rule interaction | Must expose trigger and cooldown | +| Tool | Route utility or narrow battle action modifier | Cannot silently consume persistent resources in battle | + +Items may be legal in multiple slots only if the catalog row declares each +budget profile. A unit cannot equip duplicate stable item IDs. Company-wide +unique effects use `unique_group`; a second copy may be equipped for its local +stats but its unique effect is visibly dormant. + +### 13.1 Behavior Hook Vocabulary + +Content can change only named hooks unless this authority is revised: + +```text +before_target, after_target +before_cast, on_cast_complete, on_interrupt +before_damage, after_damage, on_critical +before_heal, after_heal, on_overheal +on_barrier_break, on_block +on_status_apply, on_status_expire +on_shift, on_forced_move, on_lane_exposed +on_aether_gain, on_signature +on_down, on_rescue +route_preview, reward_draft, secure_cache, recover, reroute +``` + +Every proc declares its condition, cooldown (minimum 0.5 s unless a fixed test +proves no loop), maximum triggers per action, and whether derived effects can +retrigger it. Default is `derived effects cannot retrigger`. + +### 13.2 Item Comparison + +Comparison shows: + +- primary and derived stat deltas; +- changed skill timing, target candidates, status chance, and resource flow; +- lost and gained interaction tags; +- effect on predicted first target and lane protection; +- chapter item-band difference, without labeling one item universally better. + +The 320-row catalog, acquisition, tiers, upgrades, salvage, and the at-least-120 +behavior-changing test are owned by the economy authority and content catalog. + +## 14. Tactical Directives + +### 14.1 Command Charges + +The company starts each standard encounter with one Command charge, holds at +most two, and can spend at most two total. The second is earned when the Command +meter reaches 100. It starts at zero and gains from nonrepeatable tactical +events: + +| Event | Gain | Per-encounter cap | +|---|---:|---:| +| Interrupt a declared major cast | 20 | 40 | +| Break an enemy Barrier or Block sequence | 15 | 30 | +| Exploit a previewed weakness/setup tag | 10 | 30 | +| First allied Downed event | 20 | 20 | +| Boss phase transition | 25 | 50 | + +Repeated hits from one action count once. Meter gain beyond 100 is discarded +after awarding the second charge. Items may redistribute gains but cannot grant +a third use. + +### 14.2 Core Directives + +The onboarding unlocks three universal directives. The player prepares exactly +two before an expedition and may change them at an Anchor. + +| Directive | Target/effect | Illegal reason examples | +|---|---|---| +| Focus Order | Mark one reachable enemy for 6 s; +1000 Target Score for actions that can legally target it; exposes its next action in event log | Target dead, untargetable, no legal allied action | +| Brace Order | One allied lane gains barrier equal to 12% of each unit's Max HP and `Anchored` for 4 s | Lane empty, both units Downed | +| Shift Order | Swap two orthogonally adjacent living allies; each gains 50% damage reduction for the 0.5 s transition | Not adjacent, Rooted, Downed, uninterruptible cast, destination reserved | + +Using a directive pauses simulation during legal target selection by default. +Confirm stamps it to the next tick and spends the charge atomically. Cancel +spends nothing. Repeating confirm with the same action ID cannot spend twice. + +Content may add directives only by exchanging targeting, timing, or risk. It +may not add raw damage/healing directives that are optimal whenever charged. + +### 14.3 Standing Orders: Bounded Automation + +After the player earns Mastery for an encounter mechanic, they may configure +one standing order: + +```text +visible condition -> one prepared directive -> legal target policy +``` + +Examples of legal conditions are `major cast with tag begins`, `front lane +becomes exposed`, or `two allies below 40% HP`. The order consumes a real +Command charge and produces the same log as manual use. It is active only in +encounters whose relevant threat tags are mastered. First-seen enemy identities, +elites, bosses, and new chapter rupture rules require manual confirmation. + +The player can disable or override the order. If its condition occurs but the +directive is illegal, no charge is spent and the exact reason is logged. This +automates solved timing labor without choosing route, build, risk, or novel +counterplay. + +## 15. Enemy AI And Telegraph Contract + +Every enemy row declares: + +```text +preferred slots and legal displacement +target candidate filter and score modifiers +basic action and major action(s) +first-major-action horizon +telegraph duration and interrupt/control response +counter tags and at least two rational responses +phase triggers and changed rules +failure contribution shown in report +``` + +### 15.1 Preview + +Before commitment, the encounter shows: + +- exact enemy slot occupancy and any hidden arrival slots as silhouettes; +- damage/pressure families, target rules, and bypass/intercept tags; +- earliest possible major action in a bounded window; +- hard-control, displacement, summon, heal, barrier, or execution capability; +- resistances and immunities as rules, not unexplained percentages; +- objective, retreat rule, 180-second Fracture Clock, and rewards; +- a comparison against the current company identifying exposure, not a + guaranteed win percentage. + +Unknown story identity may hide name/art, but never a mechanic needed to make a +fair preparation decision. + +### 15.2 In-Battle Telegraph + +- A directive-relevant major action has at least 2.0 simulation seconds of + telegraph; bosses have at least 3.0 on first use. +- Telegraph shows caster, legal targets or area, completion tick, effect tags, + and interrupt/control response. +- At 2x/4x, the first occurrence of an unmastered major action invokes a + `Decision Hold`: slow to 1x and maintain at least two real seconds before + completion. The player may disable automatic hold only after passing its + tutorial; pause and event-log inspection remain available. +- A changed target updates the line and reason. A hidden retarget is forbidden. +- Fake telegraphs are allowed only when the encounter preview explicitly names + deception as the mechanic and supplies a readable tell. + +## 16. Battle Speed, Pause, And Fracture Clock + +Available speeds are pause, 1x, 2x, and 4x. Speed multiplies how quickly fixed +ticks are presented, not cooldowns, chances, command timestamps, or rewards. +The player may pause during all single-player battles, target directives while +paused, inspect status/event history, and change future AI priorities only +after the encounter, never while paused. + +Standard battles target 35-120 simulation seconds. At 150 seconds, visible +`Fracture Pressure` begins: + +- all damage dealt increases 25% per ten seconds; +- all healing and new barrier strength decrease 20% per ten seconds; +- damage increase caps at +100%; healing/barrier reduction caps at -80%. + +At 180 seconds the route rupture completes and the encounter is a defeat unless +its declared objective was already satisfied. The preview and battle clock +state this. Content must still pass simulation without relying on the final +collapse as its normal resolution. + +## 17. Downed, Rescue, Retreat, And Victory + +At zero HP, a normal adventurer becomes `Downed`: + +- leaves target candidacy except for rescue/execution actions; +- no longer protects a rear slot or contributes passive company effects unless + the passive explicitly declares a Downed behavior; +- retains statuses whose rows declare persistence; +- starts an eight-second Rescue Window. + +A legal rescue returns the unit at 25% Max HP, clears hard control, grants one +second untargetable recovery, and can occur once per adventurer per encounter. +After the window expires the unit is `Lost for encounter`, not deleted. Winning +with a Lost unit adds one Strain after battle. + +Retreat becomes legal ten seconds after battle start unless the preview declares +a shorter/longer objective-specific boundary in 5-30 seconds. It channels for +three seconds, can be interrupted by a declared effect, and returns through the +failure transaction appropriate to difficulty. The UI previews exact cache, +Supply, and Strain consequences before channeling. + +Victory occurs only when the declared objective predicate is true, such as all +required enemies Downed, a channel protected, or a rescue completed. Killing +unrequired summons does not silently satisfy an objective. Outcome is checked +after simultaneous event application. + +## 18. Battle Diagnosis + +The result report is an explanation system, not a damage leaderboard. It stores +and presents: + +1. the player's pre-battle predicted first target and exposed lane; +2. actual first target, first major telegraph, and first plan divergence; +3. earliest lane protection loss with cause; +4. first preventable major hit, control, or failed command; +5. every Downed event and its preceding five seconds of causal events; +6. effective damage, prevention, healing, control, setup, and resource value; +7. wasted overheal/barrier, unreachable casts, fizzles, and dormant unique effects; +8. the top three counterfactual categories, framed as evidence rather than an + auto-equip recommendation; +9. reward and failure transaction IDs for support/debug views. + +Contribution score is never used for rewards and is not collapsed into one +rank. The player can compare two attempts on the same encounter seed. A +training replay may apply one changed loadout/slot without rewards to validate +the counterfactual. + +## 19. Expedition Route System + +### 19.1 Route Graph + +An expedition contains four to seven nodes from these mechanical categories: + +| Node | Decision purpose | +|---|---| +| Conflict | Test formation/build against visible enemy pressure | +| Hazard | Trade Supplies, Strain, or a loadout tag against route risk | +| Opportunity | Choose one of multiple reward/acquisition directions | +| Camp | Recover, reconfigure, or secure at opportunity cost | +| Story | Authored character/world choice with declared mechanical consequence | +| Elite | Combine at least two pressures for a higher-value secured reward | +| Anchor | Bank cache, save route progress, transform/reveal network | + +At each decision, two or three reachable nodes are visible. At least one route +must be viable without the newest random item. Scouting can reveal one extra +node or hidden parameter but cannot be mandatory to avoid an untelegraphed +counter. + +### 19.2 Supplies + +Supplies are expedition capacity, start at six by default, and cap at nine. +Baseline actions: + +| Action | Supply cost | Result | +|---|---:|---| +| Recover | 1 | Clear one Strain from one adventurer or heal company to full at Camp/Anchor | +| Secure early | 2 | Bank current Unsecured Cache without ending expedition | +| Deep scout | 1 | Reveal one extra branch and exact reward family | +| Reroute | 1 | Return to prior fork without rerolling revealed nodes | +| Extra profession change | 1 | Change one additional active profession at an Anchor | + +Chapter and difficulty may alter starting amount by at most +/-2. Supplies are +never sold for premium currency and do not regenerate with real time. Unused +Supplies convert to a modest end-expedition Crown bonus defined in the economy +authority, so preserving them is valuable but not always dominant. + +### 19.3 Unsecured Cache And Anchors + +Encounter rewards enter the Unsecured Cache unless marked immediately secured. +An Anchor atomically: + +- banks the cache into persistent inventory/currencies; +- updates chapter route and transformation state; +- clears the encounter journal and creates a recovery checkpoint; +- grants the anchor's one free profession change; +- exposes the next route choice and exact withdrawal result. + +The player may voluntarily withdraw at any noncombat node. Withdrawal banks or +forfeits cache according to difficulty, shown before confirm. Failure behavior +is specified in the save/failure authority. + +## 20. Guild Systems + +The Guild provides persistent functions without timers: + +- roster and company assembly; +- profession learning, mastery trials, and free respec; +- equipment inventory, deterministic crafting, upgrades, and salvage; +- chapter/route selection and threat archive; +- training replays with no rewards; +- catalog, achievements, accessibility, localization, and settings; +- postgame Reweave laws and completion records. + +Facilities unlock new actions or acquisition paths. Facility levels may not be +pure percentage multipliers or require waiting in real time. A solved repetitive +action may become a batch operation only after the single-item result and costs +are understood. + +## 21. Content Schemas + +### 21.1 Profession Row + +```text +profession_id, base_or_advanced, parent_base_id +primary_function, secondary_function, preferred_rank +base_stats and growth vector +trait, basic, techniques[], passives[], signature +default priority rows and legal target policies +aether loop, counter tags, vulnerability +branch opposition statement +unlock/mastery trial and chapter placement +two counterfactual validation encounters +presentation and accessibility events +``` + +### 21.2 Skill Row + +```text +skill_id, owner_profession, tags +candidate filter, target score modifiers, retarget policy +Base, Coefficient, PowerSource, damage/heal/control type +windup, cast, recovery, cooldown, aether delta +status rows and proc hooks +AI condition vocabulary and telegraph +illegal/fizzle reasons +animation, VFX, SFX, caption, reduced-motion alternative +fixed validation input and expected event outputs +``` + +### 21.3 Enemy Row + +Uses the telegraph contract in Section 15 and must add progression placement, +reward family, distinct mechanic statement, two counter-responses, interaction +with at least two older mechanics, and failure-report language. A palette/stat +variant without a new preview-to-counter question is not an identity. + +### 21.4 Encounter Row + +```text +encounter_id, chapter, route tags, objective +enemy identities/slots/levels, seed rules +preview fields and hidden-but-nonstrategic story fields +Fracture Clock, retreat rule, reward budget +expected battle duration and decision timestamps +normal/active/efficient/adversarial/returning profile assertions +victory, defeat, recovery, and training-replay result +``` + +## 22. Static Balance And Validation Gates + +Before a systems implementation may claim automated verification: + +- all 12 base professions have exactly two branches; +- all loadouts satisfy fixed slot counts; +- all skills use declared hooks, target filters, and timing bounds; +- all enemy major actions have preview and telegraph records; +- no content exceeds defense, critical, barrier, control, or directive caps; +- every item proc has a cooldown/trigger cap and recursion declaration; +- target prediction matches first simulated target for deterministic fixtures; +- replay hash matches for identical seed and command timeline; +- each branch pair passes both opposed counterfactual fixtures; +- every encounter has at least two rational response tags and one no-random- + acquisition completion path; +- standard battles resolve before 180 seconds in all five pacing profiles; +- invalid commands return one enumerated reason and spend no resource; +- no report recommends a specific item as a universal answer. + +## 23. Required Fixed Test Vectors + +| Vector | Setup | Expected boundary | +|---|---|---| +| Front protection | F2 and R2 versus standard melee | R2 is not a candidate until F2 is Downed/Broken | +| Ranged protection | Same setup versus ranged | R2 remains legal with -120 score; preview shows it | +| Focus legality | Focus marked protected rear against melee-only party | No illegal forced target; reason logged | +| Simultaneous down | Two units complete lethal actions same tick | Both actions apply; both units Downed | +| Barrier cap | Repeated barrier grants over 50% Max HP | Excess discarded and reported as waste | +| Control chain | Three stuns inside ten seconds | duration reduction then immunity; action window preserved | +| Directive duplicate | Same confirm action ID submitted twice | one charge spent, one event applied | +| Speed parity | Same commands at 1x and 4x ticks | identical outcome hash | +| Save parity | Suspend during cast and resume | same next event and final hash | +| Proc recursion | Derived damage owns same hook as source | no retrigger unless row explicitly permits within cap | +| Long battle | Objective incomplete at 150/180 s | pressure escalates, then declared defeat at 180 | +| Branch counterfactual | Fixed base with branch A/B encounters | each branch leads one fixture without universal dominance |