# Headless Playground: Run Lifecycle Cut Map Date: 2026-09-17 Status: Imagination pass, cut map. Nothing here has landed. Anchors are against `codex/item-provenance` HEAD `1e647953`. Mechanism claims marked **(probe)** were run headless against the real catalog `GameData/Aetheria.cc` (read-only) and the authored `Assets/Resources/Settings.asset`. Run and player stores went to a temp directory. The probe was built with `--artifacts-path` in scratch, so this tree got no `bin`/`obj` writes. CultLib was a temporary detached worktree at `a0813c6`, since removed. The probe source is not kept; §2.8 records what it did. ## 0. Target Operator, 2026-09-17: player inputs "map directly to the same entity inputs the AI uses". An agent should be able to "spin up a playground ... generate galaxies, puppeteer an entity around yourself using the existing agent routines", and "This should be possible without involving Unity". Ends: - An agent (Hands or Soul) runs a scripted session headless. The script can: - start a new game (galaxy, entrance zone, player ship); - drive the pilot by hand-set entity inputs or by an existing `Agent`; - dock, undock, warp between zones, take hits, die, and save; - reopen the stores and Continue. - The session emits a compact trace. It exits non-zero when an expectation fails or an exception escapes. - First consumers: - the headless half of the CultCache-migration play smoke (`docs/cultcache-migration-cut.md:2739-2765`); - the headless half of the provenance Cut C operator checks (`docs/item-provenance-cut.md` §6, "Operator-only checks after Cut C"); - the reopen defect in §2.6. Invariants: - **One owner of the run lifecycle.** The playground and `ActionGameManager` both call the same ServerShared owner. Neither re-implements new game, zone entry, warp, dock, save, Continue or death. - **One input surface.** Manual input, agent routines and playground commands write the same entity fields and call the same behavior methods. The playground has no private input path and writes no entity state the player cannot reach. Exceptions are named commands that call the same owner the Unity console calls. - **Determinism.** A scenario with a given seed produces the same trace twice. The probe's two runs matched line for line. - **The playground never touches `GameData/run.cc` or `GameData/player.cc`.** It opens the catalog read-only and keeps its run and player stores in a directory it is given. Non-goals: - No rendering, no Unity, no new daemon, no CultMesh surface. - No headless ballistics. Whether a shot geometrically hits stays with Unity physics (fork D). - No trade menu, no action-bar UI, no input devices. - Tier colour, properties panel, input screen and CultCache Studio rendering stay operator checks. ## 1. Verdict on the operator's claim **Mostly true for movement and firing. False for how combat resolves, and the AI's combat state cannot run without Unity.** - True: - Player movement and AI movement write the same `Ship.MovementDirection` (`Ship.cs:27`). Player: `ActionGameManager.cs:1201`. AI: `Agent.cs:67,73,77`. - Both write the same `Entity.LookDirection` (`Entity.cs:42`). Player: `ActionGameManager.cs:1189-1192`. AI: `MoveTo.cs:26`, `Combat.cs:111`, `Agent.cs:66`. - Both write the same `Entity.Target` (`Entity.cs:40`). Player: `ActionGameManager.cs:366-397`. AI: `Minion.cs:14`. - Both fire through the same `Weapon.Activate/Deactivate`. Player: `ActionBarSlot.cs:190-204`, via the action bar at `ActionGameManager.cs:411-412`. AI: `Combat.cs:56,106,108`. - Player-only inputs, all plain entity writes that an agent could make: - `TractorPower` (`ActionGameManager.cs:1214-1216`); - `OverrideShutdown`, `HeatsinksEnabled`, shield `Enabled`, `Sensor.Ping` (`:339-362`); - gear `IActivatedBehavior` (`ActionBarSlot.cs:159-168`); - consumables (`ActionBarSlot.cs:119-122`, `Entity.TryActivateConsumable`). - Player-only lifecycle actions. These are the orchestration this map moves: - interact, which means warp, dock or undock (`ActionGameManager.cs:298-320`); - tow (`:889-913`); - boarding another docked ship (`InventoryPanel.cs:117-118`). - **False: combat resolves in Unity.** - `InstantWeapon.OnFire` only raises an event (`InstantWeapon.cs:183`). The projectile is a Unity effect manager (`EntityInstance.cs:203-204`). - Hits are physics colliders (`HullCollider.cs:18`, `GuidedProjectile.cs:170`). - Turning a hit into armor, item and hull damage is `EntityInstance.DamageSchematic` (`EntityInstance.cs:276-314`), with hit-shape and penetration at `:330-395`. - NPC death removes the entity from the zone at `:437`. Loot drops in the same place (`:405-435`), rolled with `UnityEngine.Random`. - Pickup is a collision trigger (`ShieldManager.cs:29`). - **(probe)** Weapon groups fired 6 `OnFire` events at an enemy 50 units ahead. Enemy hull stayed 500.0 -> 500.0. - **False: `CombatState` needs Unity-written data.** It indexes `Ship.HardpointTransforms` (`Combat.cs:101`). Only `EntityInstance.cs:516` writes that dictionary, from barrel transforms. - **(probe)** A `Minion` with a target throws `KeyNotFoundException: 'Energy Hardpoint '` on its first combat step. - Every NPC agent that acquires a target would throw the same way headless. - The weapons' own direction reader already has a fallback (`Behaviors.cs:24-43`). `CombatState` does not use it. ## 2. Body findings ### 2.1 Where the run lifecycle lives today All of this is Unity code: | Concern | Anchor | Unity dependencies | |---|---|---| | Store composition | `ActionGameManager.cs:43-63` (static, `Application.dataPath`) | path only | | Handoff across scene load | statics `CurrentGalaxy`, `IsTutorial` (`:96-97`), written by `MainMenu.cs:104-105,126,138,152,166`, read by `SectorMap.cs:114-310` | `SceneManager.LoadScene` (`MainMenu.cs:106,139,167`) | | New game: clear | `MainMenu.cs:112` | none | | New game: galaxy | `MainMenu.cs:125,148` (`UnityEngine.Random.value` background noise), `:127-141,153-169` (`Task.Run`, then `Observable.NextFrame`) | Random, UniRx main-thread scheduler | | ItemManager | `ActionGameManager.cs:264`; RNG clock-seeded at `ItemManager.cs:20` | `Debug.Log` | | Start / Continue | `StartGame` `:725-770`: spawn player ship `:733-744`; Continue resolves the docked child `:751-762`; action bar restore `:764-767` | renderer binding, `SectorMap` reveal | | Zone entry | `PopulateLevel` `:639-675`: generate/unpack `:643-654`; move pilot `:659-666` | `ZoneRenderer.LoadZone`, `Debug.Log` | | Wormhole placement (a game rule) | `ZoneRenderer.cs:222-231` (`dir * Pack.Radius * GameSettings.WormholeDistanceRatio`) | lives in a MonoBehaviour | | Warp | detect `ActionGameManager.cs:312-316`; `EnterWormhole` `:615-637`, which saves on arrival (`:635`) | `ZoneRenderer.WormholeInstances` as the wormhole list | | Dock / undock / tow | `:801-823`, `DoDock` `:825-843` (cameras, menus), `:845-887` (dialogs), `:889-913` | cameras, dialogs | | Board a docked ship | `InventoryPanel.cs:117-118` | UI button | | Save | `SaveRun` `:241-249`, called at quit `:236` and warp `:635` | action-bar slots (`:246`) | | Death | `BindToEntity` subscribes `Death` -> `Die` (`:1053`); `Die` `:1080-1115` clears the run (`:1088`) | `Time.time`, `Observable.EveryUpdate` post-fx | | Tick | `Update` `:1151-1220`: input `:1189-1216`, then `Zone.Update(Time.deltaTime)` `:1218` | `Time.deltaTime`, pause flag | | Dead code | `IntroCutscene` `:772-799`; its only call is commented out (`:760`) | coroutine, `Time.time` | ### 2.2 Already headless - `Aetheria.Shared/Aetheria.Shared.csproj` compiles `Assets/Scripts/ServerShared/**` plus UniRx (`UniRxLibrary`) and Ink with no Unity defines. It is the Unity-independence check. - Galaxy generation, zone generation, `Zone`, entities, behaviors, agents, `RunSave`, `AetheriaStores` and `ItemManager` all run under it. The probe measured: - galaxy seed 42: 196 zones; - the first zone with ships and stations: 7 entities and 4 agents; - a player `LonginusX` spawned through `LoadoutGenerator`; - thrust by hand-set `MovementDirection` reached 142 m/s in 5 s; - a `Minion` patrol moved the player ship 642 units in 10 s; - `TryDock` and `TryUndock` succeeded (`Entity.cs:721-755`); - `Ship.EnterWormhole` followed by stepping fired `OnEnteredWormhole` (`Ship.cs:82-90,372`); - `Death` fired on hull damage (`Entity.cs:277-280`); - `RunSave.Capture` and `RunSave.Commit` wrote a 489 KB `run.cc`. - Settings: `GameSettings` is a ScriptableObject (`GameSettings.cs:11`) holding ServerShared classes. - `tools/AetherDb/AuthoredSettings.cs` reads them from the asset YAML. The probe placed every field (0 unplaced). - Two lifecycle inputs are Unity-only `GameSettings` fields: `StartingHullName` (`GameSettings.cs:17`, authored `LonginusX`) and `WormholeDistanceRatio` (`:23`, authored 0.75). - Randomness: - `ItemManager.Random` is clock-seeded (`ItemManager.cs:20`). - `Galaxy` is clock-seeded only when `seed == 0` (`Galaxy.cs:108,158`). - `Zone` seeds from the zone name (`Zone.cs:54`). - `Zone.Update` runs belt updates on `Task.Run` (`Zone.cs:144`). It is still deterministic (probe: identical traces). ### 2.3 Agents - The agent API is `Agent.Update(dt)` (`Agent.cs:47-56`) over a `BaseState` graph. - `Minion` (`Minion.cs:7-21`) patrols (`PatrolOrbits.cs`), auto-targets the first visible enemy (`:14`), and enters `CombatState`. - Agents are created only for packed non-player ships at zone construction (`Zone.cs:88-93,99-106`) and are updated before entities (`:147-150`). - Nothing ever removes one from `Zone.Agents`. - The player ship never gets an agent. - An agent held in a zone's list would stay behind when its ship warps (`PopulateLevel` moves the entity, not agents). - There is no "fly to a point" state. `MoveToState` is abstract and its only concrete state is `MoveToOrbitState` (`MoveTo.cs:7-37`). ### 2.4 AetherDb - Commands: `census`, `station-fit`, `hardpoint-fit`, `loadout [seed]`, `save`, `factions`, `dangling`, `settings`, `settings-dump` (`Program.cs:18-35`). - Stores open through `AetherDb.Open`, which calls `AetheriaStores.Open` with `GameData/run.cc` hard-wired (`AetherDb.cs`). `save` (`Program.cs:349-410`) is the only played-save reader. - It already owns `AuthoredSettings` (YamlDotNet) and references `Aetheria.Shared`, so it has everything the playground needs. ### 2.5 Tests at HEAD **(probe)** `dotnet test tests/Aetheria.Shared.Tests` at `1e647953` with CultLib `a0813c6`: **32 passed, 2 failed.** Both failures are `MessagePackSerializationException: Failed to deserialize SavedZone value`: - `LoadoutTests.MaterializedLotsSurviveSaveAndReload` - `RunSaveTests.CommitKeepsOnlyReachableLots` This contradicts the "34 tests green" verification that `docs/item-provenance-cut.md` sets for Cut B. ### 2.6 The reopen defect, confirmed **(probe)** Reopening a run store that holds a `SavedZone` with any entity throws: ``` MessagePackSerializationException: Failed to deserialize SavedZone value. TypeAccessException: No hash-resistant equality comparer available for type: CultMath.int2 ``` - The failing field is `EntityPack.PersistedBehaviors`, a `Dictionary` (`EntitySerializer.cs:200`), written at `:35-40` and read at `:126-130`. - The player ship's dictionary was **empty** (0 persisted behaviors) and it still threw. MessagePack builds the dictionary's comparer before reading any entry. - `CultMessagePackSecurity` runs `UntrustedData` and adds a comparer only for `CultRecordRef` keys. - No other run-store type has a struct dictionary key. `SavedGame` uses `int` keys, the ledger uses `int`, and `PlayerSettings` uses `string`. - Consequence: **Continue has been unable to load any run that visited a zone** since entities entered the run store under this security. Migration smoke step 6 cannot pass. Unity reads through the same CultLib serializer, which is inferred, not run here. ### 2.7 Asides found in passing (not this cut's to fix) - `TargetNearest` picks the **farthest** visible enemy: `MaxBy(length(...))` (`ActionGameManager.cs:378-379`). - The interact loop enters every wormhole in range, then calls `Dock()` anyway (`:312-317`). - `SaveRun` passes `DockedEntity ?? CurrentEntity` (`:245`), but `BindToEntity` nulls `DockedEntity` (`:946`). The order is fragile, not wrong today. ### 2.8 The probe (discarded) A scratch console referencing `Aetheria.Shared` and `AuthoredSettings.cs`. It: 1. Loaded authored settings. 2. Opened the stores (catalog read-only; run and player in temp). 3. Generated a galaxy with seed 42 and set `ItemManager.Random` to seed 7. 4. Generated zones outward from the entrance until one held ships and stations. 5. Spawned the player ship, drove it by hand, then by a `Minion`. 6. Forced a target, fired groups by hand, then docked, undocked and entered a wormhole. 7. Killed an NPC by hull damage, then saved, disposed and reopened. Traces from two runs were identical. ## 3. Authority map **Owner: `Run`, a new ServerShared class (`Assets/Scripts/ServerShared/Run.cs`).** It owns one live run's lifecycle: start, zone entry, pilot, dock state, warp, save, Continue and death. There is one instance per run. It holds no Unity type. - **Inputs:** - the `CultCache` from `AetheriaStores.Open`, composed by the caller; - `GameplaySettings`, `ZoneGenerationSettings`, `PlanetSettings`; - a `uint seed` for `ItemManager`; - `Action log`; - for a new run, a caller-built `Galaxy` and `isTutorial`; - `dt` per step; - commands from either lowering; - `SavedActionBarBinding[]` at save, owned by the Unity action bar (the playground passes empty). - **Outputs:** - state: `Galaxy`, `ItemManager`, `Zone`, `Pilot` (the piloted `Entity`), `Station` and `Bay` when docked, `TowingStation`, `Ended`; - events: `ZoneEntered(Zone)`, `PilotChanged(Entity)`, `Docked(Entity, EquippedDockingBay)`, `Undocked`, `WarpArrived(GalaxyZone)`, `Saved`, `Died(CauseOfDeath)`; - store writes through `RunSave.Commit` and `RunSave.Clear` only. - **Derived state:** - `ActionGameManager.CurrentEntity`, `.Zone`, `.ItemManager`, `.DockedEntity`, `.DockingBay` and `.TowingStation` become read-only projections of `Run`, for display only. - `ZoneRenderer.WormholeInstances` becomes render-only: its keys are `Zone.Wormholes`, and it is no longer the wormhole list gameplay reads. - `SectorMap` reads `Run.Galaxy` for display. - **Forbidden writers after the cut:** - `ActionGameManager` may not call `RunSave.Clear`, `RunSave.Capture`, `RunSave.Commit`, `ZoneGenerator.GenerateZone` or `new Zone`, and may not add or remove the pilot in `Zone.Entities`. - It may not construct `ItemManager`, spawn the player ship, subscribe `Death` to end the run, or set `CurrentEntity`, `DockedEntity`, `DockingBay` or `TowingStation`. - `MainMenu` may not call `RunSave.Clear` or construct `Galaxy(cache, saved)`. - `InventoryPanel` may not write `CurrentEntity` or `DockingBay.DockedShip`. - `ZoneRenderer` may not create `Wormhole` objects. - The playground may not write `Position`, `Velocity`, `Hull.Durability` or zone membership directly. Its `hit` command goes through the damage owner (fork D). - **Shared paths:** - Manual input and agent input write the same entity fields (§1), and both go before `Run.Step`. Unity writes input in `Update`, then calls `run.Step(Time.deltaTime)`. The playground updates its pilot agent inside `Run.Step`, before `Zone.Update`, so the order matches. - Direct interaction (Unity's Interact key), programmatic interaction (playground `dock`/`warp`) and Continue's docked landing all commit through `Run.TryDock`, `Run.TryEnterWormhole` and `Run.Land`. - A new run and Continue share `Run.EnterZone`. - Warp arrival and quit share `Run.Save`. - **Pilot agent:** - `Run.PilotAgent` (nullable) is owned by `Run`, not by `Zone.Agents`, so it follows the pilot across warps. - Unity leaves it null. It may never be non-null while Unity input is enabled. - `Zone.Agents` stays the owner of NPC agents. - **Deletion line:** - `ActionGameManager`: bodies of `SaveRun`, `EnterWormhole`, `PopulateLevel`'s simulation half, `StartGame`, `Dock`, `DoDock`'s state half, `Undock`'s checks, `TowShip`, `Die`'s clear, and `IntroCutscene` (entirely); - statics `CurrentGalaxy` and `IsTutorial`; - `MainMenu.cs:104-105,112`; - `ZoneRenderer.cs:222-231`'s wormhole construction; - `ItemManager.cs:20`'s clock seed. All of these go in the same cut that adds `Run`. None survives as a fallback. Unity dependencies, each injected or cut: | Dependency | Where | Disposition | |---|---|---| | `Time.deltaTime` | `:1218` | injected: `Run.Step(float dt)` | | `Time.time` | `IntroCutscene`, `Die` post-fx | cutscene deleted; post-fx stays in Unity, on `Died` | | `UnityEngine.Random` | `MainMenu.cs:125,148` (background noise), `EntityInstance.cs:413-428` (loot) | noise stays in the menu as a galaxy-generation input; loot roll moves to ServerShared on `ItemManager.Random` (fork D) | | Clock RNG | `ItemManager.cs:20` | cut; the seed is a constructor argument, and Unity passes a clock-derived one | | Coroutines | `IntroCutscene` | deleted (dead) | | UniRx | `Observable.NextFrame` in the menu, `EveryUpdate` in `Die` | stay in Unity; `Run` uses C# events, and `Entity.Death` (UniRx, headless-compiled) is what `Run` subscribes to | | `Debug.Log` | `:264`, `:657`, `MainMenu` | injected `Action` | | Scene load | `MainMenu` | stays; the handoff static becomes `ActionGameManager.NewRun : (Galaxy, bool)?`, command-only, consumed once in `Start`; null means Continue | | MonoBehaviour state | `_currentEntity`, `DockedEntity`, `DockingBay`, `TowingStation`, `Zone`, `ItemManager` | projections of `Run` | | Barrel transforms | `EntityInstance.cs:516` -> `HardpointTransforms` | render-owned aim; `CombatState` stops depending on it (fork H) | ## 4. Cuts Build budget for every cut: - Packages: `Aetheria.Shared` (netstandard2.1), `tools/AetherDb` and `tests/Aetheria.Shared.Tests` (net10.0), Debug only. - CultLib at `a0813c6`, unmodified, under fork R (a). - No new project, target, package or schema store. - Build host: this Windows workstation, which is also the target for the headless checks. - `Assembly-CSharp` is proven only by Unity batchmode with the editor closed, per `docs/item-provenance-cut.md` §6. This is the operator's call. - Headless commands use `--artifacts-path ` while another agent is reading the tree. ### Cut 0: make a run with entities reopenable (fork R) **Ruled (operator, 2026-09-17):** fork R is the pairs array. It lands with the provenance Cut B fix batch; see `docs/item-provenance-cut.md`. - `EntitySerializer.cs:200`: `PersistedBehaviors` becomes `(int2 position, PersistentBehaviorData[] data)[]`, matching `Equipment` at `:197-199`. - Key 5 is kept. The wire shape changes from a map to an array; saves are discarded and no `GameData/run.cc` exists. - `:35-40` packs pairs. - `:126-130` builds a local lookup at unpack. - `RunSaveTests.cs` `BarePack` initializer: `Array.Empty<...>()`. - Verification: - The two HEAD-red tests go green: 34 passed. - Mutation: restore the `Dictionary` type. Both tests go red with the `int2` comparer message. - Add `ReopenedPackKeepsPersistedBehaviors` to `RunSaveTests`. A pack with two positions, each with one persisted behavior, commits and reopens, and the positions and data are equal. - Mutation: pack drops `data`, so the test goes red. - Mutation: unpack ignores the lookup, so the test goes red. - Negative: `rg -n "Dictionary log)` 1. `RunSave.Clear`. 2. `ItemManager` over `RunSave.Lots`, seeded. 3. `EnterZone(Entrance)`. 4. Spawn the player ship per `:734-743`. 5. Set the pilot. Returns a live run. - `static Run Continue(CultCache, …, uint seed, Action log)` - Returns null when there is no `SavedGame`. - Otherwise `Galaxy(cache, saved, log)`, then `EnterZone(saved zone)`, then `Land(saved entity)`. - `Land` handles an orbital entity per `:753-756`: pilot is the `IsPlayerShip` child, and the run is docked there. - `void Step(float dt)` - Throws if `Ended`. - Updates `PilotAgent`, then `Zone.Update(dt)`. - `void EnterZone(GalaxyZone)`: the rule from `:643-666`. It raises `ZoneEntered`. - `bool TryEnterWormhole()` - Picks the nearest `Zone.Wormholes` entry within `GameplaySettings.WormholeExitRadius`. Requires the pilot to be a `Ship`, not mid-animation, and undocked. - On `OnEnteredWormhole`: 1. `EnterZone(target)`. 2. Discover adjacent zones. 3. `ExitWormhole` at the back-link wormhole with `WormholeExitVelocity * ItemManager.Random.NextFloat2Direction()`. 4. `Save(lastActionBar)`. 5. Raise `WarpArrived`. - `EquippedDockingBay TryDock()`: the rule from `:803-821`, within `DockingDistance`. - `UndockResult Undock()`: `Ok`, `NotDocked`, `MissingCockpit`, `MissingThruster`, `MissingReactor`, `BayNotEmpty`. Check order as `:850-885`. - `bool Board(Ship)`: docked only; the ship must be the station's `IsPlayerShip` child; updates `Bay.DockedShip`. - `void Tow()`: the rule from `:891-911`. - `void Save(SavedActionBarBinding[] actionBar)` - `RunSave.Capture(cache, Galaxy, Zone, Station ?? Pilot, isTutorial, actionBar)`, then `Commit(…, ItemManager.Lots)`. - No-op when `Ended`. - Remembers `actionBar` for warp saves. - Death: `Run` subscribes `Pilot.Death` whenever the pilot changes. On death: 1. `Ended = true`. 2. `RunSave.Clear`. 3. Dispose subscriptions. 4. Raise `Died(cause)`. - `Agent PilotAgent { get; set; }`: setting it while `Ended` throws. - Tests (in `RunTests`, same project, fixture catalog as `LoadoutTests`). Each is paired with the mutation that must kill it: | Test | Asserts | Mutation that must kill it | |---|---|---| | `NewRunSpawnsPilotInEntrance` | pilot is a `Ship` with `IsPlayerShip`, in `Zone.Entities`, `Zone.GalaxyZone == Galaxy.Entrance`; the run store is cleared of a prior `SavedGame` | `New` skips `RunSave.Clear`; spawn omits `Zones.Entities.Add` | | `WarpMovesPilotAndSaves` | stepping after `TryEnterWormhole` lands the pilot in the target zone, out of the old zone's entities, with `SavedGame.CurrentZone` equal to the target index after reopen | arrival skips `Save`; `EnterZone` leaves the pilot in the old zone | | `ContinueLandsDocked` | save while docked, reopen, `Continue`: `Station` is the saved orbital, `Pilot` is its player child | `Land` binds to the orbital itself | | `DeathEndsAndClears` | hull death clears every run record; `Step` throws; `Save` writes nothing | `Died` handler omits `Clear`; `Ended` not set | | `PilotAgentFollowsWarp` | a `Minion` set as `PilotAgent` still updates the pilot (position changes) after a warp; `Zone.Agents` of both zones exclude it | agent added to `Zone.Agents` | | `WormholesAreZoneOwned` | `Zone.Wormholes.Length == AdjacentZones.Count` and positions follow the ratio | ratio ignored | - Verification: - Headless build and tests green. - Unity batchmode has no `error CS`. - Negative greps: - `rg -n "RunSave\.(Clear|Commit|Capture)" Assets/Scripts --glob '!ServerShared/**'` is empty. - `rg -n "CurrentGalaxy|IsTutorial\s*=" Assets/Scripts` is empty. - `rg -n "new Wormhole" Assets/Scripts` matches only `Zone.cs`. - `rg -n "new ItemManager\(" Assets/Scripts` matches only `Run.cs`. - `rg -n "ZoneGenerator\.GenerateZone|new Zone\(" Assets/Scripts --glob '!ServerShared/**'` is empty. - `rg -n "CurrentEntity\s*=[^=]" Assets/Scripts --glob '!ServerShared/**'` is empty. - `rg -n "DateTime\.Now" Assets/Scripts/ServerShared/ItemManager.cs` is empty. - Ledger: - `ActionGameManager` about -190 +45; `MainMenu` -4 +2; `ZoneRenderer` -9 +3; `InventoryPanel` -2 +1; `SectorMap` ±12 renames; `ItemManager` ±1; `Zone` +10; `Run.cs` about +190; tests about +200. - Statics: -2 +1. - Net production code is about +40. That buys the invariant: the lifecycle has one owner, and every rule it holds existed before in a MonoBehaviour. ### Cut 2: combat and death resolve without Unity (forks H, D) - `Combat.cs:101`: `shouldFire` reads `testWeapon.Direction`, the same reader shots use (`Behaviors.cs:24-43`). Its fallback is hull-relative item rotation; with Unity running, the articulated barrel transform wins as today. - Damage owner: `EntityInstance.cs:276-314` (`DamageSchematic`) and `:330-395` (hit-shape) move to `Entity`: - `void ApplyHit(HullHit hit)` with `HullHit { Damage, Penetration, Spread, DamageType, Source, HullUv, LocalDirection }`; - `void ApplySplash(float damage, DamageType type, Entity source, float2 localDirection)`. - The only Unity-specific step, `transform.InverseTransformDirection`, becomes a rotation by `Ship.Rotation` (`Ship.cs:71`) at the caller. `HullCollider` subscribers call these methods. - Death owner: `Zone` subscribes each entity's `Death` when it is added. On death: - remove the entity from `Entities` and its agent from `Agents`; - roll drops with `ItemManager.Random` against `LootDropProbability`. That field moves from `GameSettings.cs:19` to `GameplaySettings`, together with `LootDropVelocity`. - Keep `Zone.Loot : ReactiveCollection`. - `EntityInstance.cs:405-437` keeps the destroy effect only. `ZoneRenderer.DropItem` lowers `Loot.ObserveAdd`. - Pickup owner: `bool Zone.TryPickUp(Entity, LootDrop)` stores the item in the first cargo bay that accepts it and removes the drop. `ShieldManager.cs:29` calls it. - Tests: | Test | Asserts | Mutation that must kill it | |---|---|---| | `CombatStateFiresHeadless` | a `Minion` ship with a target in range steps 10 s headless without throwing and raises at least one `OnFire` | revert `:101` | | `HardpointHitDamagesItemThenHull` | a hit on hardpoint index k with damage greater than armor plus item durability lowers that item's durability to 0 and the hull by the remainder | armor not subtracted; hull skipped | | `NpcDeathRemovesEntityAndAgent` | after hull death the entity and its agent are gone from the zone | removal omitted | | `LootDropsAreSeeded` | two zones from the same seed drop identical item lists | roll uses a clock RNG | | `PickUpStoresAndRemoves` | the item lands in cargo and the drop is gone; a full bay leaves the drop | drop removed on failure | - Verification: - Headless green; Unity batchmode has no `error CS`. - Negative: `rg -n "Random\.value|onUnitSphere" Assets/Scripts/Gameplay/EntityInstance.cs` matches only visual effects, not the drop decision. - Negative: `rg -n "Entities\.Remove" Assets/Scripts --glob '!ServerShared/**'` is empty. - Operator: a Unity fight still damages and drops loot. - Ledger: `EntityInstance` about -110 +12; `Entity` +95; `Zone` +45; `ShieldManager` ±3; `Combat` ±1; tests +180. Net production about +40. It moves rules; it adds none. ### Cut 3: `AetherDb play` - `AetherDb.cs`: `Open` takes `dataDir`. Run and player paths come from it. It defaults to `GameData` for the existing commands and is required for `play`. - `Program.cs`: `case "play": return Play(args)`. - Usage: `play --data [--seed ]`. - `play` refuses a `--data` that resolves to `/GameData`. - New `tools/AetherDb/Playground.cs`. It is a line interpreter over `Run` with no simulation rules of its own. One command per line; `#` starts a comment. | Command | Calls | |---|---| | `new [tutorial] [galaxy-seed=]` | `Galaxy(...)` from authored settings, then `Run.New` | | `continue` | `Run.Continue`; fails the scenario when null | | `reopen` | dispose cache, `AetheriaStores.Open` again (quit/relaunch; the layer where §2.6 shows) | | `step ` | `Run.Step(1/60)` repeated | | `move ` / `look ` / `tractor <0..1>` | pilot entity fields, as `ActionGameManager.cs:1189-1216` | | `target nearest\|none\|` | `Pilot.Target.Value` | | `fire on\|off` | `WeaponGroups[g].weapons` Activate/Deactivate, as `ActionBarSlot.cs:190-204` | | `gear on\|off` | `IActivatedBehavior` Activate/Deactivate | | `pilot manual\|minion\|patrol\|goto station \|goto wormhole ` | `Run.PilotAgent` | | `dock` / `undock` / `board ` / `warp` / `tow` | `Run.TryDock` / `Undock` / `Board` / `TryEnterWormhole` / `Tow` | | `hit [hardpoint ]` | `Entity.ApplyHit` (Cut 2) | | `pickup all` | `Zone.TryPickUp` for drops within `DockingDistance` | | `save` | `Run.Save(empty)` | | `expect ` | facts: `ended`, `zone`, `docked`, `pilot.hull`, `zone.entities`, `run.savedgame`, `lots.absent`, `lots.mismatched`, `cargo.count` | | `state` | trace one state line | - `goto` needs `MoveToPositionState : MoveToState` in `MoveTo.cs` (about 6 lines), wrapped in a one-state `Agent`. It is the only new agent code. - The trace goes to stdout, one line per step command and per `Run` event: `t= zone= k=v…`. `state` adds pilot position, velocity, hull, target, docked, entity and agent counts, lot count and `run.cc` bytes. - An exception prints its type, message and first frame, then ends the scenario. - Exit code is failed expectations plus escaped exceptions. - `lots.absent` and `lots.mismatched` reuse the checks in `Program.cs:399-408`. They are extracted to one method that `save` also calls, not copied. - First smoke, `tools/AetherDb/scenarios/lifecycle.play`, checked in: ``` new galaxy-seed=42 state move 0 1 step 5 pilot goto station 0 step 60 dock expect docked == true undock pilot goto wormhole 0 step 60 warp step 5 expect run.savedgame == true reopen continue expect zone == expect lots.absent == 0 expect lots.mismatched == 0 target nearest pilot minion step 30 hit pilot 100000 expect ended == true expect run.savedgame == false ``` - Hands fixes the literal zone name after the first run. The scenario checks that it reproduces, not what it is. - Verification: - `dotnet run --project tools/AetherDb -- play tools/AetherDb/scenarios/lifecycle.play --data ` exits 0. - Running it twice gives byte-identical traces. - Mutation: revert Cut 0, and the scenario exits non-zero at `continue` with the `int2` message. - Mutation: `Run.Died` omits `Clear`, and `expect run.savedgame == false` fails. - Negative: `rg -n "RunSave\.|ZoneGenerator|\.Position\s*=|Durability\s*=" tools/AetherDb/Playground.cs` is empty. - Ledger: `Playground.cs` about +220; `AetherDb.cs` ±4; `Program.cs` +3 and ±10 (extraction); `MoveTo.cs` +6; scenario +26. No new target. ### Cut 4: consumer scenarios These are scenario files only; no code. - `cultcache-smoke.play` covers migration smoke steps 3-8 minus the rendering and UI parts: - new, warp, warp again with the `SavedZone` count constant (`expect run.savedzones == `, a new fact); - reopen and continue on the same zone and entity; - reopen before any step and check every visited zone still holds contents; - die, then the run is cleared. - Steps 1-2 (`player.cc` from settings UI), 3's input screen and 9 (loadout UI) stay operator-only. - `provenance-c.play` covers the Cut C checks: - new; kill an NPC with `hit`; `pickup all`; - `expect cargo.count > 0`; - warp; reopen; continue; - `expect lots.absent == 0`, `expect lots.mismatched == 0`; - die; `expect run.savedgame == false`. - Tier colour, Manufacturer row, trade purchase and Studio rendering stay operator-only. ## 5. Forks **R. Reopen defect.** Blocking: every Continue and two HEAD tests. - (a) `PersistedBehaviors` as a pairs array. This is local, matches the sibling pack fields, and saves are discarded anyway. - (b) CultLib: a hash-resistant comparer for CultMath value types in `CultMessagePackSecurity`. That is a foundation change with a new pin and a Unity package release, and it keeps a map for 0-12 entries. - (c) Key persisted behaviors by equipment index. It saves bytes but couples to equipment order, which `Pack` does not promise. - **Recommend (a).** **P. Where the playground lives.** - (a) `AetherDb play`. It already has settings, stores and the save checks. - (b) Scenarios only as xunit tests. They cannot use authored settings without dragging YamlDotNet into tests, and agents cannot puppeteer interactively. - (c) A new `tools/AetherPlay` executable, which duplicates store and settings loading for no second consumer. - **Recommend (a),** with lifecycle rules tested in xunit (Cut 1 and 2 tests) and sessions in `play`. **H. How `CombatState` decides to fire.** - (a) Read `Weapon.Direction`, the same reader the shot uses. - (b) A ServerShared articulation model owning barrel aim, with Unity rendering it. That is correct under gimbals but a new subsystem with no playground need yet. - (c) The playground writes `HardpointTransforms`. Rejected: a second writer compensating for a missing owner. - **Recommend (a).** **D. How far combat goes headless.** **Ruled (operator, 2026-09-17): none of (a)-(c).** Hit detection goes away entirely, as `docs/three-gates-scope.md` "Fire control" already planned: "We wanted to get rid of hit detection anyway, remember? Just roll the dice based on weapon stats, targeting system stats (new subsystem) and sensor state." Cut 2 is re-mapped as fire control in `ServerShared`: a hit is a roll over weapon stats, the stats of a new targeting-system subsystem, and sensor state. The playground's `hit` stand-in is not needed. - (a) Move damage application, death removal, loot roll and pickup into ServerShared; Unity keeps hit detection; the playground's `hit` supplies hits. - (b) (a) plus headless ballistics. That is a projectile simulation Unity would have to adopt, or else two truths about hits. It needs its own map. - (c) Nothing moves; the playground's fights stop at `OnFire`, and the Cut C kill-and-loot check stays operator-only. - **Recommend (a).** The operator asked for fight and loot. Without (a) or (b) the playground cannot kill anything by the rules the game uses. **S. The two Unity-only lifecycle settings.** - (a) Move `StartingHullName`, `WormholeDistanceRatio` and (Cut 2) `LootDrop*` into `GameplaySettings`, with a text edit of `Settings.asset` while Unity is closed. - (b) Pass them as `Run` constructor arguments read from `GameSettings`; the playground reads them by name from YAML. That leaves two readers of one authored value. - (c) A new `RunRules` bundle, which is a type with no owner the existing settings class lacks. - **Recommend (a).** **N. Is the scene handoff static acceptable?** Low-blocking. - (a) `ActionGameManager.NewRun : (Galaxy, bool)?`, consumed once by `Start`. - (b) `MainMenu` builds the whole `Run` on its generation thread. That moves zone generation's run-store upserts off the main thread, and the `CultCache` threading contract is not checked here. - **Recommend (a).** ## 6. Subtraction ledger | Cut | Removed | Added | Targets, schemas, stores | |---|---|---|---| | 0 | `Dictionary` field and map-building pack code, ~6 | pairs pack/unpack ~6; test ~25 | `EntityPack` key 5 wire shape map -> array; no new schema | | 1 | `ActionGameManager` ~190 (incl. dead `IntroCutscene` 28), 2 statics, `MainMenu` 4, `ZoneRenderer` 9, `InventoryPanel` 2, clock seed | `Run.cs` ~190; `Zone` +10; AGM handlers ~45; 1 static; tests ~200 | 0 targets; `Settings.asset` two keys move | | 2 | `EntityInstance` ~110 | `Entity` ~95; `Zone` ~45; tests ~180 | 0 targets; two settings keys move | | 3 | extracted duplicate of the `save` lot check | `Playground.cs` ~220; `MoveTo` +6; scenario 26 | 0 targets; `AetherDb` gains one command | | 4 | — | 2 scenario files | — | Net production code across Cuts 0-3 is about +300. Tests are about +400. No executable, package, daemon or store is added. Rules move from MonoBehaviours to ServerShared, and the only genuinely new behavior is `MoveToPositionState` and the scenario interpreter. In exchange, Continue works again (Cut 0), and agents can falsify lifecycle, save and provenance claims without the editor. ## 7. Risks - **Unity batchmode is the only proof for Cuts 1-2's `Assembly-CSharp` edits.** It needs the editor closed. The operator's in-editor play remains the proof for the lowering (cameras, menus, action bar, pickup visuals). - **`Zone` subscribing `Death` changes NPC death timing in Unity.** Removal now happens inside the damage call rather than in `EntityInstance`'s subscriber. The operator's fight check covers it. - **The playground's `hit` is not ballistics.** A scenario that passes proves damage, death, loot and save. It does not prove that shots connect in the game. - **Cut B's recorded green is contradicted by §2.5.** Soul should rerun the suite before trusting any provenance verification that reopens a store.