diff --git a/docs/locomotion-cut.md b/docs/locomotion-cut.md new file mode 100644 index 000000000..47d47d872 --- /dev/null +++ b/docs/locomotion-cut.md @@ -0,0 +1,638 @@ +# Locomotion: Control Allocation and Capability-Aware AI + +Date: 2026-09-22 + +Status: target and cut map, from an Imagination pass. None of it has landed. Every anchor is against +`origin/codex/item-provenance` at `cd846916`; the working tree on `codex/fire-control-10` (`e8fbb6a6`) has an +identical tree for every file named below. The first half of this document is the **target** (the ends). The second +half is the **cut map** (the means). When the campaign closes, split the target out as +`docs/locomotion-target.md` and keep this file as history. + +Claims marked **(probe)** come from running code: scratch builds of `Aetheria.Shared` from `cd846916` against +CultLib `45c2f40`, run in the session scratchpad. That covers catalog dumps, a legacy-msgpack decode, base-commit +flight measurements and a solver comparison. None of the probe sources are kept. Each result below says what was +run. The base suite passes 244/244 in that scratch copy. + +## Rulings + +Operator, 2026-09-22: + +- **Problem statement.** "We're gonna need much smarter locomotion AI if they're to survive getting a thruster + shot out. Longinus (non X) had one big thruster in the back and two attitude thrusters in the front. Losing an + attitude thruster means you can't rotate that way anymore. Losing a thruster on the Djinn usually means some form + of crab walking just became optimal. Naively trying to use a thruster that's been shot out makes them real easy + to cheese." +- **R1, two layers.** (1) **Control allocation owns which thrusters fire.** Each live actuator contributes a + body-frame wrench (Fx, Fy, τ) per unit throttle, with throttle in [0,1]. A bounded least-squares solve finds the + throttles for the desired wrench (Johansen & Fossen 2013 control-allocation survey). This replaces the rotation + buckets and the strafe torque compensation. Thrusters that are destroyed, unpowered, disabled or degraded drop + out of the matrix or scale down in it. (2) **The AI plans with the allocator's achievable set.** For a desired + Δv it scores candidate headings by achievable acceleration along Δv plus turn time in the directions the ship can + still rotate. Crab walking and the long way round emerge from that scoring; neither is special-cased. +- **R2, the same-inputs invariant.** "Player and AI are controlling the same ship with the same inputs, this is an + Aetheria invariant." The player's controls go through the same allocator, through the same input surface the AI + writes. Any second path that bypasses it is a forbidden writer. +- **R3.** A capability-aware **combat facing/tactics** layer is wanted as its own later cut. Example: a one-way + turner keeps its target drifting the way it can turn and leans on its turret arcs. This document maps it at + target-shape level only. +- **R4.** If CultMath lacks a bounded least-squares solver, CultMath gets one, as a CultLib cut. Aetheria does not + grow a local helper. CultMath has none (probe: `packages/cultmath/src/CultMath` at `45c2f40` holds vector types, + `math`, `BatchMath`, `Voronoi` and `Random`, with no linear solver of any kind). + +Self, relaying an operator answer, 2026-09-22. This is the layer split, stated precisely: + +- **Below the inputs**, shared by player and AI, is the ship's own controller plus the allocator. It turns toward + `LookDirection` and realises `MovementDirection` with whatever actuators are live. **Choosing a feasible turn + direction belongs here**, including the long way round when one rotation direction is dead. If it lived in the + AI planner, a player ship with a dead attitude thruster would still stick when looking toward its dead side. + Holding heading against torque coupling (strafing with an off-centre thruster) also belongs here. +- **Above the inputs**, AI only, is the heading planner. It decides what to write into + `LookDirection`/`MovementDirection`, for example to turn sideways and crab-walk. The player makes that choice by + hand. +- The long-way test therefore belongs to the shared-controller cut and drives `LookDirection` directly, as the + player would. The crab-walk test belongs to the planner cut. + +--- + +# Part I: Target + +## Objective + +A ship that loses actuators keeps flying as well as its remaining actuators allow, whether a player or an AI is +flying it. The AI picks headings and thrust directions from what the ship can still do, so shooting out a thruster +creates a real handicap and not an exploit. + +## Invariants + +1. **Same inputs.** A ship is commanded only through `Ship.MovementDirection` (body frame, each component a + fraction of the ship's capacity along that half-axis) and `Entity.LookDirection` (world-frame heading command; + the controller reads only its `xz`). The player writes both (`Gameplay/ActionGameManager.cs:1254`, `:1263`). The + AI writes the same two fields. Nothing else commands a ship's actuators. Identical inputs to identical ships give + identical actuator throttles, whoever wrote them. +2. **One owner for actuator commands.** The ship controller (new, `ShipControl`, below) is the only writer of + `Thruster` and `AetherDrive` throttles. `Ship.cs`'s mixer, its rotation buckets and its strafe compensation stop + existing, and do not survive as a mode or a fallback. +3. **The allocator reads live actuator state every tick.** An actuator's column is derived each tick from its live + stats and liveness: `EquippedItem.Active` (enabled, thermally online, durability online), a power grant above the + same epsilon `Thruster.Execute` uses, and the current resolved `Thrust` (or the drive's own stats) with its + durability, heat and power curves applied. No bucket, cache or event-pruned set decides whether an actuator + counts. A repaired or re-powered actuator rejoins by the same read that dropped it. +4. **Manual and programmatic inputs share one commit path.** A player keypress, an AI state write, and any future + scripted or network input all land in the same two fields, and they reach the actuators by the same + `ShipControl` step inside `Ship.Update`. No input source writes `Thruster.Axis`, `AetherDrive.Axis` or + `Entity.Direction` directly. +5. **Heading changes only through actuators.** `Entity.Direction` is written by actuator execution + (`Thruster.Execute`, `AetherDrive.Execute`), by wormhole scripting (`Ship.ExitWormhole`), by spawn placement + (`ActionGameManager.cs:848`) and by save unpack (`EntitySerializer.cs:66`). The controller does not write it. + Today's snap-to-look lerp (`Ship.cs:280-284`) is a free, thrusterless rotation, and it goes. +6. **Kinematic rotation is retained.** Rotation stays kinematic: yaw rate is proportional to live throttle + (`Thruster.cs:106-107`, `AetherDrive.cs:154-155`), with no angular momentum. Nothing found here argues for + raising it. It keeps turn time exact (angle divided by rate), which the planner relies on. It also matches the + operator's model ("losing an attitude thruster means you can't rotate that way anymore"): with no momentum, + there is no coast. +7. **A dead actuator never receives throttle.** A destroyed, disabled or unpowered actuator gets zero throttle, + not a saturated request it cannot honour. +8. **Capability is one model.** Turn time, turn direction, rotation capacity and translation capacity are computed + in one place (`ShipControl`), from the same effectiveness matrix the allocator solves with. The AI queries them + and never recomputes a private estimate. + +## Canonical implementations + +- **Solver:** CultMath (`F:\Projects\CultLib\packages\cultmath`), a box-constrained linear least-squares solver, + added by Cut 1. It is the only numerical authority. Aetheria composes the problem and calls it. +- **Allocation reference:** T. A. Johansen and T. I. Fossen, "Control allocation: A survey," *Automatica* 49(5), + 2013. Its weighted-least-squares form with priorities is what `ShipControl` states. The active-set method follows + O. Härkegård, "Efficient active set algorithms for solving constrained least squares problems in aircraft control + allocation," CDC 2002, which is bounded-variable least squares in Stark and Parker's sense. + +## Out of scope + +- **Fire-control Cut 12** (edge-on hit placement in `FireControl.cs`, `Entity.ApplyHit`, `DamageSchematic`) is + being mapped concurrently by another Imagination pass. Cuts 1 to 3 here touch none of those files. The allocator + is a read-only downstream consumer of item destruction (`ItemDamage`, `Entity.cs:488`). **Overlap:** Cut 4 (combat + facing) will rewrite `Agents/States/Combat.cs:88-127`, and presenting armour edge-on is exactly what Cut 12's hit + placement rewards. Cut 4 must be mapped after Cut 12 lands. +- **The old AetheriaEve/CultMesh/daemon rebuild** is taxidermy. It is not precedent and not a consumer. +- Thruster geometry (the normalized moment-arm `Thruster.Torque`, `Thruster.cs:64-69`, which ignores lever length + and uses unweighted shape cells for centre of mass) is the game's model and stays as authored. Arrival braking in + `MoveToState`, docking approach and formation flight are also out. + +## Not consumers + +- `Assets/Scripts/Gameplay/*` presentation (`ShipInstance` particles, audio parameters) reads throttles and never + writes them. +- `TurretController` writes `Entity.LookDirection` for turret entities. That is the AI above the inputs for a + non-ship, and it does not drive ship actuators. See the audit. + +## 0b: identity, lifecycle, authority + +Nothing persistent changes. Actuator wrench columns, capacities, the chosen turn direction and planner state are +runtime-derived per tick, or per planner cadence, and are never saved. + +| Kind | Named by | Lifecycle | Decides | +|---|---|---|---| +| Actuator column (runtime) | the `Thruster`/`AetherDrive` behaviour instance on an `EquippedItem` | rebuilt every tick from live stats; appears and disappears with liveness | `ShipControl` derives; item state (durability, heat, power, `Enabled`) is owned by `EquippedItem`/`PowerBus` as today | +| `MovementDirection`, `LookDirection` (runtime) | fields on `Ship`/`Entity` | overwritten each frame by whoever flies the ship | player (`ActionGameManager`) or AI (`Agent` layer), never both on one ship (`Zone.cs:111` gives agents only to `!IsPlayerShip`) | +| Committed turn direction, planner plan (runtime) | fields on `ShipControl` / `Agent` | reset on wormhole, dock, spawn | `ShipControl` / `Agent` | +| `ThrusterData`, `AetherDriveData`, `HullData.Hardpoints/Shape` (persisted, catalog) | catalog record key | authored | unchanged; read only | +| `GameplaySettings.TorqueFloor`, `TorqueMultiplier`, `AetherTorqueMultiplier` (authored, `Settings.cs:205-207`; values in `Assets/Resources/Settings.asset`: 0.5, 0.1, 0.1) | field name | authored | unchanged values. `TorqueFloor` changes role; see Cut 2 | + +This campaign adds no authored field. If Hands finds it needs a tunable, that is an operator question, and any new +field on a persisted CultCache document must be nullable (MessagePack nil rule). + +--- + +# Part II: Body map (what the probes established) + +## The mixer today + +`Ship.Update` (`Ship.cs:251-292`) runs before `base.Update` executes behaviours. The agents' writes come earlier +still, because `Zone.cs:170-173` updates agents before entities. The steps: + +1. `RecalculateThrust` (`Ship.cs:147-247`) sums per-bucket thrust over thrusters whose item is `Active`. +2. It zeroes every thruster's `Axis` (`:256`). +3. Strafe: the right and left buckets get `±MovementDirection.x`, minus a torque compensation for the thrusters + whose torque sign matches the bucket total (`:257-274`). +4. Forward and reverse buckets add `±MovementDirection.y` (`:275-276`). +5. Rotation: `deltaRot = sqrt(|dot(look, right)|)·sign` (`:278-285`) is added to the clockwise bucket and subtracted + from the counter-clockwise bucket (`:287-288`). +6. `AetherDrive.Axis = (MovementDirection.y, MovementDirection.x, deltaRot)` (`:291`). There is no allocation for + drives at all. + +Buckets are built once in `Activate` from mount rotation and from `Thruster.Torque` against +`TorqueFloor` (`:102-118`). `RemoveThruster` prunes them permanently on `ItemDestroyed` (`:123`, `:133-143`). + +`Thruster.Axis` saturates to [0,1] (`Thruster.cs:45-49`). `Execute` (`:94-115`) applies `Velocity -= facing·input· +Thrust/Mass·dt`, then rotates `Direction` kinematically by `input·Torque·Thrust·TorqueMultiplier/Mass·dt`. Its gate +is `input > .01 && PowerSupply > 1e-4`. + +## Findings (probe) + +Fixtures here are built from the legacy catalog (next section): hull shape, hardpoints, thruster items with +constant `Thrust` (Large Drive 250000, Medium Drive 200000; mass 100 each), `TorqueFloor` 0.5, `TorqueMultiplier` +0.1. Each ship sits at (37, −12) facing `normalize(0.8, 0.6)`, runs 3 warm-up ticks, is reset, and is measured over +one tick at dt 0.02. Body-frame acceleration is (r, f) in m/s². Heading rate is compass degrees per second, +clockwise positive. + +**Torque factors** (`Thruster.Torque`, the sine of the moment arm): Longinus mains ±0.159 (below the floor, so +never used for rotation), attitude thrusters ±0.998. Djinni stern 0 / ±0.161, laterals ±0.727 (aft) and ±0.867 +(fore), bow 0. + +**Base flight table** (`cd846916`, after warm-up). These are the Cut 2 pins: + +| Input | Longinus (r, f, °/s) | Djinni (r, f, °/s) | +|---|---|---| +| forward `(0,1)` | 2.37, 172.38, 0 | 0.11, 55.56, 0 | +| reverse `(0,−1)` | 0, 0, 0 | 0, −18.52, 0 | +| strafe right `(1,0)` | 0, 0, 0 (compensation zeroes the lone attitude thruster) | 34.03, 0.42, 0 (axes 1.00 / 0.84) | +| strafe left `(−1,0)` | 0, 0, 0 | −34.03, 0.42, 0 | +| look 90° right | 68.97, 0, +394.33 | 0.01, 0.59, +169.13 | +| look 90° left | −68.97, 0, −394.33 | 0.01, −0.50, −169.13 | +| look 30° right | 48.77, 0, +278.84 | 0, 0.30, +119.59 | +| look directly behind | 0, 0, 0, **and `|Direction|` falls to 0.96** | same | +| forward+strafe `(.707,.707)` | 1.18, 121.89, 0 | 24.12, 39.49, 0 | + +The small cross terms (2.37, 0.42) are real. `Execute` rotates `Direction` thruster by thruster within one tick, so +later thrusters push along an already-rotated nose. The allocator cannot see this, so pins need a tolerance for it. + +**Defects the table exposes:** + +- **Dead-side stick.** On a Longinus with `Th.CCW` destroyed, looking 90° left gives a heading error of 90.0° + after 30 s. It never turns. Looking right, it reaches within 2° in 0.32 s, the same as intact. +- **Main-thruster cheese.** On a Djinni with all three stern thrusters destroyed, `Agent` plus `MoveToState` toward + a point 300 m to port leaves the ship at speed 0 after 120 s. `Agent.Accelerate` points at Δv and burns forward + thrusters only (`Agent.cs:64-68`), and it never reaches the strafe branch. Intact, the same run arrives in + 4.34 s. With only Stern 2 lost it arrives in 4.98 s; with only Port Aft lost, 4.40 s. +- **Snap-to-look.** Inside `|sin error| < .01`, `Ship.cs:283` lerps `Direction` toward the look vector, which is a + rotation no thruster pays for. When the look is directly behind, the lerp goes through the origin and shrinks + `|Direction|`, and thruster force scales with that length (`Thruster.cs:105` uses the unnormalized item + direction). Base also turns *slower* as error passes 90°: `deltaRot` follows `sin`, so it is zero at 180°. +- **First tick.** Items are not yet `Active` on the first `Update` after `Activate`, so the first-tick strafe + compensation divides by a zero count (NaN, unused) and the strafe fires uncompensated. +- **`TurnTime` is wrong and unused.** `Ship.cs:61-66` divides angle by the sum of torque *factors* over mass, which + is unitless nonsense: 261535 s for a Longinus 90° turn. It has no consumer. +- **Permanent pruning.** `RemoveThruster` never restores a thruster whose durability comes back, and `Recalculate*` + reads `Active` while the mixer still commands inactive thrusters. +- **The live catalog's only ship flies on a drive.** `GameData/Aetheria.cc` holds one ship hull, **LonginusX** + (mass 2500, drag 0.1, 6×17), with an `AetherDrive` hardpoint and **no `Thruster` hardpoint**. It moves on + "Traction" (rotor mass (30,20,5), λ (0.5,1,1), MaxRpm 40000..80000). Two thruster designs exist ("deep space + burnout", "Large Drive"), but no live ship can mount them (`docs/content-batch-one.md` §1 says the same). + **AetherDrive is therefore the load-bearing actuator for the player today**, and the allocator must reproduce its + base behaviour exactly. +- **Existing tests sit on an off-centre thruster.** `BrownoutTests`/`ConditionRatioTests` equip a one-cell thruster + by `TryFindSpace` onto a 5×5 hull. It lands at (1,1) with `Torque` −0.707, and `MovementDirection (0,−1)` fires it + while it spins the ship. Under an allocator that holds heading, a lone off-centre thruster cannot fire without + rotating, so those fixtures must be re-seated (Cut 2). + +## Legacy hull layouts (probe) + +The live catalog is the post-breach minimal rebuild, so absence there proves nothing. The layouts come from the +git-LFS objects of `GameData/Legacy/AetherDB.2021-03-05.msgpack` (`142998fd…`) and `AetherDB.2021-04-14.msgpack` +(`21ce7bd2…`), both present in `.git/lfs/objects`, decoded with MessagePack `ConvertToJson`. Shape cells are +`bool[w,h]`, flattened as `x*h + y`, with y = 0 at the stern. + +**Longinus** (2021-04-14: mass 2500, drag 0.1, 6×17; the 2021-03-05 copy has mass 5000). The shape matches the +live LonginusX's. Rows from y = 0: `.####.` ×4, `######` ×5, `.####.` ×2, `..##..` ×6. + +| Hardpoint | Pos | Shape | Rotation | +|---|---|---|---| +| Th.L | (1,0) | 2×2 | Reversed (pushes forward) | +| Th.R | (3,0) | 2×2 | Reversed | +| Th.CW | (2,14) | 1×2 | CounterClockwise (pushes starboard, nose right) | +| Th.CCW | (3,14) | 1×2 | Clockwise (pushes port, nose left) | + +**The data has two aft 2×2 thrusters, not one.** The operator remembers "one big thruster". Fixtures follow the +data (see Q3). + +**Djinni** (mass 10000, drag 0.2, 14×17). Rows from y = 0: `....######....`, `...########...`, +`..##########..`, `.############.` ×2, `##############` ×5, `.############.`, `...########...` ×3, +`....######....`, `.....####.....`, `......##......`. + +| Hardpoint | Pos | Shape | Rotation | +|---|---|---|---| +| Stern 1 | (6,0) | 2×1 | Reversed | +| Stern 2 | (5,1) | 2×1 | Reversed | +| Stern 3 | (7,1) | 2×1 | Reversed | +| Port Aft | (4,4) | 1×2 | CounterClockwise | +| Port Fore | (4,11) | 1×2 | CounterClockwise | +| Starboard Aft | (9,4) | 1×2 | Clockwise | +| Starboard Fore | (9,11) | 1×2 | Clockwise | +| Bow | (6,14) | 2×1 | None (pushes aft) | + +Legacy thruster items used for the fixtures: Large Drive 2×2, 250000 thrust, mass 100. Medium Drive 2×1, thrust +100000..300000 (fixtures use a constant 200000), mass 100. Small Drive 1×1, 75000. + +## Solver choice (probe) + +The comparison ran on the fixtures' own normalized columns, plus a 16-column doubled Djinni: 2000 random wrench +demands each, cost measured against a 20000-iteration projected-gradient reference, double precision, +allocation-heavy scratch C#, Release build. + +| Method | Worst excess cost | Suboptimal cases | Mean time | +|---|---|---|---| +| Primal active set (bounded-variable LS, Härkegård WLS form) | ≤ 7e-15 | 0 in every case | 1.8–9.5 µs (n 3–8), 32–38 µs (n 15–16); ≤ 30 iterations cold | +| Redistributed pseudo-inverse | up to 4e3 | 270–1564 of 2000 (n ≤ 8) | about half the active set's time | + +**Pick the active set.** It is exact, its cold-start cost is bounded, and it warm-starts from last tick's solution. +The redistributed pseudo-inverse saves about half the time and is wrong in up to 78% of cases on these very +matrices. A production float implementation without allocations will be faster than the scratch numbers. + +## Consumer audit + +`cd846916`, every `*.cs` outside `Assets/Plugins`. "Dies" means deleted, not deprecated. + +| Surface | Readers / writers | Fate | +|---|---|---| +| `Ship.MovementDirection` (`Ship.cs:27`) | W: `ActionGameManager.cs:1263` (player), `Agent.cs:67,73,77` (AI); tests `BrownoutTests.cs:143,402`, `ConditionRatioTests.cs:184,193,243,258`. R: `Ship.cs:261-291` | **Survives** as the translation input. Its meaning is defined by `ShipControl` (fraction of capacity per half-axis) | +| `Entity.LookDirection` (`Entity.cs:55`) | W: `ActionGameManager.cs:1254` (player), `Agent.cs:66`, `MoveTo.cs:26`, `Combat.cs:126`, `TurretController.cs:72,75` (turret entities; no `EntityTypeRestriction`, `TurretController.cs:14-15`). R (as heading): `Ship.cs:278`. R (as aim): `LockWeapon.cs:94`, `GuidedProjectileManager.cs:56`, `EntityInstance.cs:404`, `ShipInstance.cs:117` (tractor), `ZoneRenderer.cs:432`, `ActionGameManager.cs:376` (reticle target pick) | **Survives** as heading command *and* aim. `MoveTo.cs:26` dies in Cut 3 (a double writer: `Accelerate` overwrites it when Δv > 20). The heading/aim conflation is Cut 4's question (Q4) | +| `Thruster.Axis` (`Thruster.cs:45-49`) | W: `Ship.cs:256-288` only. R: `ShipInstance.cs:139` (particles), `Thruster.cs:88` (power request), `:96` (audio), `:102-111` | Getter **survives**. The public setter **dies**; only `ShipControl` commands throttle | +| `AetherDrive.Axis` (`AetherDrive.cs:81-85`) | W: `Ship.cs:291` only. R: drive internals, audio `:170` | Same as `Thruster.Axis` | +| `IAnalogBehavior` (`Behaviors.cs:96-99`) | implemented by `Thruster.cs:40`; consumer only a comment, `Entity.cs:2007` | **Dies** (Cut 2 deletes first) | +| Bucket sets `_forward/_reverse/_right/_left/_clockwise/_counterClockwiseThrusters`, `_thrusterItems`, `_aetherDrives`, `_aetherDriveItems` (`Ship.cs:30-39`) | `Ship.cs` only | **Die** | +| `ForwardThrust`, `ReverseThrust`, `LeftStrafeThrust`, `RightStrafeThrust`, `ClockwiseTorque`, `CounterClockwiseTorque`, `Left/RightStrafeTotalTorque`, `Left/RightStrafeTorqueThrusters` (`Ship.cs:50-59`) | written by `RecalculateThrust`, read by the mixer; **no reader outside `Ship.cs`** (grep, including Unity side and tests) | **Die** | +| `Ship.TurnTime` (`Ship.cs:61-66`) | no consumer | **Dies**; replaced by `ShipControl.TurnTime` (Cut 2), consumed in Cut 3 | +| `RemoveThruster`, `RemoveAetherDrive`, their `ItemDestroyed` subscriptions (`Ship.cs:123-143`) | internal | **Die**; liveness is read live (invariant 3) | +| `Agent.Accelerate` (`Agent.cs:58-79`), `FORWARD_DELTA_THRESHOLD`/`THRUST_DELTA_THRESHOLD` (`:16-17`) | called by `MoveTo.cs:27`, `Combat.cs:127` | **Rewritten** in Cut 3 (planner). Signature kept | +| `Agent.TopSpeed` (`Agent.cs:26`) | `MoveTo.cs:25`, `Combat.cs:127`. No live catalog item carries `VelocityLimit` or `VelocityConversion` (probe), so it is 100 everywhere | Survives | +| `GameplaySettings.TorqueFloor` (`Settings.cs:205`) | `Ship.cs:115,118` | **Survives with a new role**: it sizes rotation authority (Cut 2) and no longer classifies which thrusters fire | +| `TorqueMultiplier`, `AetherTorqueMultiplier` | `Thruster.cs:107`, `AetherDrive.cs:155` | Survive; also enter the yaw-rate row of each column | +| `Entity.Direction` writers | `Thruster.cs:106`, `AetherDrive.cs:154`, `Ship.cs:79` (wormhole), `Ship.cs:283` (snap), `ActionGameManager.cs:848` (spawn), `EntitySerializer.cs:66` | `Ship.cs:283` **dies** (invariant 5); the others survive | +| `Entity.Velocity` external writers | `HullCollider.cs:15` (collision impulse), `ShieldManager.cs:79` (bounce), `VelocityConversion.cs:41`, `VelocityLimit.cs:48` | Not control; these are external forces and constraints. Untouched | +| Undock capability check (`ActionGameManager.cs:913`) | `GetBehavior() == null` | Survives. It could later read the capability model; not this campaign | +| Mining, Survey, HaulingTask, StationTowing (`Agents/Tasks/*.cs`) | data-only task classes; no movement code (grep) | Not consumers. `PatrolOrbitsState` drives `MoveToOrbitState`, which Cut 3 covers | +| Player input path | `Input.Player.Look` → `_entityYawPitch` → `LookDirection` (`:1250-1254`); `Input.Player.Move` → `MovementDirection` (`:1261-1264`). No other action writes motion (grep of `Input.Player.*`: targeting, heat, shield, stance, tractor, ping, UI) | **Already on the shared surface**. The only bypasses are the ones `Ship.cs` itself holds (the snap, direct `Axis` writes), and both die in Cut 2 | + +Out-of-scope note: the working tree has an uncommitted change to `Assets/Scripts/AetheriaInput.cs` (a "Cycle Target +Item" action). That is fire-control work, and it does not touch motion. + +--- + +# Part III: Cut map + +## Status header + +Status: cut map. Ends are owned by Part I above; this section owns the means. + +Nothing has landed. + +Open: Q1 and Q2 block Cut 2's pins. Q3 blocks only fixture naming. Q4 blocks only Cut 4. + +Follow-ups outside this campaign: +- `TurretController` has no `EntityTypeRestriction`, so equipping it on a ship would create a third + `LookDirection` writer racing the player or agent. Restrict it to non-ship hulls when turret work next opens + (`TurretController.cs:14`). +- `Thruster.Execute` applies rotation per thruster inside the tick, which couples later thrusters' force to earlier + thrusters' rotation. It is a small artefact, and it is `Thruster.cs`'s to fix, not the allocator's. +- `AetherDrive.Execute` logs "FUCK FUCK FUCK FUCK" on NaN velocity (`AetherDrive.cs:157-158`), a leftover probe. + +## Cut 1. CultMath: bounded least squares (CultLib) + +- **Repo/branch:** `F:\Projects\CultLib`, a branch from `45c2f40` (Aetheria's pinned `CultLibRevision`, + `Directory.Build.props`). Depends on nothing. +- **First:** run `dotnet test packages/cultmath/tests/CultMath.Tests` green at base and record the count. +- **Deletes first:** none. This is a pure addition, and it is the ruled owner fill (R4). +- **Adds:** one C# file in `packages/cultmath/src/CultMath/` with a static solver for + `min ||A x − b||²` subject to `lo ≤ x ≤ hi`. It serves a dense, small problem (m ≤ ~24 rows, n ≤ ~24 columns). + Rules: + - The method is a primal active set (bounded-variable LS). Each iteration solves the free set by Cholesky on the + normal equations, or by QR if Hands prefers conditioning. It terminates on KKT: at each bound the gradient sign + must be consistent with that bound. + - `float` in, `Span`/`ReadOnlySpan` arguments, caller-supplied workspace. No allocation per call. + - `x` is both warm start and result. The solver clamps it to the box first. + - It returns an iteration count or status, has a bounded iteration cap, is deterministic, and keeps its + last feasible iterate on a cap hit. A rank-deficient free set is handled (the caller adds a small ridge row, + and the solver must not throw on a singular pivot). + - Naming stays boring and HLSL-adjacent per `docs/design.md` Rules, for example a + `CultMath.BoundedLeastSquares` static class. It is C#-only like the intercept helpers (`math.cs`). No Rust or + HLSL mirror, because it is not a batch kernel and no shader needs it. +- **Tests** in `packages/cultmath/tests/CultMath.Tests`: + - `InteriorOptimumEqualsNormalEquations`: a problem whose unconstrained optimum lies inside the box returns it. + Pins the free-set solve. + - `KktHoldsOnRandomBoxedProblems`: randomized problems up to 24×16 are checked against a projected-gradient + reference to 1e-4 relative cost, and each active bound's gradient sign is checked. Pins optimality and the + multiplier test. + - `AllBoundsActive`, `ZeroColumn`, `DuplicateColumns`: degenerate columns return without throwing and are + optimal. Pins rank handling. + - `WarmStartMatchesColdStart`: a solution from a perturbed warm start equals the cold solution. Pins + that the start does not bias the result. + - `AsymmetricBounds`: `lo = −1, hi = 1` on some columns and `[0,1]` on others. Pins bidirectional actuators. + - Fixtures must not be degenerate: non-square, non-identity A, and b not in A's range. +- **Release:** build the Unity package (`packages/cultmath/scripts/build-unity-package.ps1`), bump + `unity/org.gamecult.cultmath/package.json` to 0.2.4, and tag `cultmath-unity-v0.2.4` by CultLib's own release + path. In Aetheria, bump `Packages/manifest.json`'s `org.gamecult.cultmath` tag and `Directory.Build.props` + `CultLibRevision` in one commit. +- **Authority map:** Owner: CultMath. Inputs: A, b, bounds, warm start. Outputs: x and status. Forbidden writers: + no least-squares or linear-solve code in `Aetheria/Assets/Scripts/**` (negative grep in Cut 2). +- **Verification:** `dotnet build packages/cultmath/src/CultMath/CultMath.csproj`; `dotnet test` of CultMath.Tests. + Aetheria's `dotnet test tests/Aetheria.Shared.Tests` still passes 244 after the bump. Unity compiles the new + package, and only the operator can check that. +- **Ledger estimate:** +150..220 lines of source and +150 lines of test in CultLib; Aetheria gets a 2-line bump. + +## Cut 2. `ShipControl`: shared controller and allocator replace the mixer + +- **Repo/branch:** Aetheria, a branch from the Cut 1 bump commit. Depends on Cut 1. +- **First:** before editing, commit the base flight numbers above as test constants, reproduced by the fixture spec + in "Findings". They are computed at `cd846916`, never captured from new code. Also run a LonginusX-with-Traction + pin at base: `AetherDrive.Axis` for each probe input is `(my, mx, sqrt(|sin e|)·sign)`, including e = 30°, which + gives `Axis.z = 0.7071`. +- **Deletes first** (separate commit, build and tests green, no behaviour change): + - `Ship.cs:61-66` `TurnTime` (6 lines). + - `Behaviors.cs:96-99` `IAnalogBehavior` (4 lines) and its mention in the `Thruster` declaration (`Thruster.cs:40`). + - `Entity.cs:2007`, the commented `IAnalogBehavior` line. +- **Deletes (behaviour commit):** + - `Ship.cs:30-39` (bucket and item sets, 10 lines). + - `:50-59` (capacity properties and strafe lists, 10 lines). + - `:96-118` (bucket construction; `Activate` keeps `base.Activate()` and gathers actuators, about 20 lines). + - `:123-124` (subscriptions) and `:127-143` (`RemoveAetherDrive`, `RemoveThruster`, 17 lines). + - `:145-249` (the `ThrustCalculation` region, 105 lines). + - `:255-291` (mixer and snap, 37 lines). + - The public `Axis` setters: `Thruster.cs:45-49` and `AetherDrive.cs:81-85` become getters plus a command method + only `ShipControl` calls. + - Total is about 200 lines out of `Ship.cs`. +- **Keeps:** `Ship.cs:253` gate (active, not in a wormhole); `:294-310` drag, position, gravity and rotation + quaternion; wormhole code; `Thruster.Execute`/`AetherDrive.Execute` physics unchanged. The throttle is still + `_input`/`_axis`, so power requests, audio and particles read what they read today. +- **Adds:** `ShipControl` in `Assets/Scripts/ServerShared/ShipControl.cs`, owned by `Ship` and stepped from + `Ship.Update` where the mixer was. It is one file and one owner. Types and rules: + - **Actuator columns.** A narrow interface implemented by `Thruster` and `AetherDrive`. There are two + implementers and one consumer; this replaces `IAnalogBehavior`. + - Each actuator reports its columns every tick: body-frame (Fx, Fy) in m/s² and yaw rate in rad/s + (clockwise positive) per unit throttle, plus bounds. It then accepts its throttles back. + - **Thruster:** one column, [0,1]. F is the negative item facing (`Rotate` of (0,1) by mount rotation) times + live `Evaluate(Thrust)/Mass`. Yaw is `Torque·Thrust·TorqueMultiplier/Mass`. + - **Zeroing:** the column is zero when `!Item.Active.Value` or `Item.PowerSupply ≤ 1e-4`, which is the same + predicate `Execute` gates on. `Thruster.Thrust` (stale, updated only in `Execute`) is not the source. + - **AetherDrive:** three axes. Translation is split into ± columns, [0,1] each, because the drive's efficiency + depends on sign and speed (`AetherDrive.cs:138`). Torque is one column, [−1,1]. + - **Drive authority is nominal.** Effectiveness is the drive's force at `MaximumRpm` from its own stats (rotor + mass, λ, λ multiplier, coupling efficiency, `AetherTorqueMultiplier`), scaled by the same liveness and by its + condition. It is not the instantaneous `Rpm`. Rotor spin-up is the drive's internal dynamics, not an + allocation decision. This choice is what keeps LonginusX exact: for a lone drive, self-consistent capacity + cancels the scale, so throttle equals input. + - **Heading controller** (below the inputs, shared): + - `look = LookDirection.xz`. A zero look means hold heading: no NaN, no command. + - Per rotation direction, rotation authority `ω_cap(dir)` is the sum of that direction's yaw-rate entries over + columns whose `|Thruster.Torque| > TorqueFloor`. Drive torque columns always count. Under Q2 (A) that is the + whole of rotation authority. **`TorqueFloor` no longer decides which thrusters fire.** It only sizes how + much rotation may be demanded. + - **Direction choice:** pick the direction that minimizes `angle_in_that_direction / ω_cap(dir)`, with + infinity where `ω_cap = 0`. This yields the long way round. Keep the committed direction unless the other + direction is faster by a margin, so symmetric ships do not dither near 180°. + - **Rate demand:** `ω_d = min(profile(e)·ω_cap, e/dt)`, where `profile(e) = sqrt(sin e)` for e ≤ 90° (base's + curve, which preserves the pins) and 1 beyond. The `e/dt` cap lands the heading without overshoot and + replaces the snap. + - It exposes `TurnTime(heading)` and `RotationCapacity(dir)` for Cut 3. + - **Translation demand:** + - `F_d = (mx·cap(±x), my·cap(±y))`, where `cap(d)` is the along-d component of the allocator's own solution to + "a huge demand along d, rotation held at zero". Capacity is self-consistent: one objective, and no second + rule for what full stick means. + - It exposes `TranslationCapacity(bodyDir)` along any body direction, same definition, for Cut 3. + - Probe values: Longinus cap(+y) 172.41, cap(+x) 13.74 (with side effects, so the demanded strafe comes out + about 0.09 m/s²). Djinni cap(+x) 37.04, cap(+y) 55.56, cap(−y) 18.52. + - **Allocation objective:** one bounded-LS call, priorities by weight separation (Johansen & Fossen § + prioritization): + - P1, yaw rate equals `ω_d`. Separation about 1e3. + - P2, translation error `F − F_d` in plain L2 (isotropic), each row normalized by the ship's largest column + magnitude. + - P3, a small ridge on throttle (about 1e-3), for tie-breaking and conditioning. + - Warm start from last tick's throttles. + - Probe: a demand-frame weighting with perpendicular error weighted k = 2 gave no benefit over isotropic + (k = 1). Keep it isotropic. + - **Budget:** 1 allocation solve plus 4 capacity solves per ship per tick. At the scratch timings that is well + under 100 µs per ship. Hands measures with a production build and reports. The fix for cost is solver + efficiency, not a cache, because a cache would be a second truth for liveness (invariant 3). +- **Per-file changes** (against `cd846916`): + - `Ship.cs:251-292`: `Update` calls `ShipControl.Step(dt)` inside the existing `:253` gate. The drag and position + code below stays. + - `Ship.cs:92-119`: `Activate` collects actuators into `ShipControl` (all `Thruster` and `AetherDrive` + behaviours). No classification. + - `Ship.cs:121-125`: the constructor drops both `ItemDestroyed` subscriptions. + - `Thruster.cs:40`: implement the actuator interface, drop `IAnalogBehavior`. `:45-49`: public getter, internal + command. `:61-71`: `Torque` stays as the geometry factor. + - `AetherDrive.cs:81-85`: same pattern. Add the nominal-authority read next to its stats. + - `tests/Aetheria.Shared.Tests/BrownoutTests.cs:111-131` and `ConditionRatioTests.cs:94-95`: equip the consumer + thruster on the hull's centre column, using `TryEquip(item, int2(2, y))` with a free y, so `Torque == 0`. These + tests pin brownout and condition, not flight. Their asserted values (for example `.1f` at + `BrownoutTests.cs:162`) must not change. Fix the fixture, never the assertion. `PowerCurveTests.cs:52-62`'s + comment about the `Axis` being clobbered becomes true for a different reason; update the wording only. +- **Authority map:** + - Owner: `ShipControl` decides every actuator throttle and the feasible turn direction. + - Inputs: `MovementDirection`, `LookDirection.xz`, current `Direction`, `Mass`, `dt`, each actuator's live + column, `TorqueFloor`/`TorqueMultiplier`/`AetherTorqueMultiplier`. + - Outputs: per-actuator throttle (`Thruster._input`, `AetherDrive._axis`); capability queries + (`TurnTime`, `RotationCapacity`, `TranslationCapacity`). + - Derived state: columns, capacities and `ω_d` are per-tick derived, never stored across ticks except the warm + start and the committed turn direction, which are command state and not truth. `Thruster.Axis` and + `AetherDrive.Axis` are display and command readbacks. + - Forbidden writers: `Ship.Update`'s mixer (gone); any assignment to `Thruster.Axis`/`AetherDrive.Axis` outside + `ShipControl`; `Ship.cs:283`'s direct `Direction` write; bucket pruning on `ItemDestroyed`; any Unity-side + write of throttles. + - Shared paths: player writes (`ActionGameManager.cs:1254,1263`) and AI writes (`Agent`, `MoveTo`, `Combat`) both + reach actuators only through `ShipControl.Step`. Wormhole exit leaves the gate closed until the animation + ends, as today. + - Deletion line: the delete commits above land before `ShipControl` gains behaviour. +- **Verification:** + - Builds: `dotnet build Aetheria.Shared`; `dotnet test tests/Aetheria.Shared.Tests -m:1 -p:CultLibRoot=…`. + Unity batchmode compile (operator, or Self when the editor is closed). + - Tests (new file `LocomotionControlTests.cs`, fixtures exactly as in "Findings": off-origin, off-axis nose with + `|fx| > |fy|`, nonzero dt, asymmetric damage): + - `IntactLonginusMatchesBase` and `IntactDjinniMatchesBase`: every row of the base table within tolerance + (2% of that ship's full-scale acceleration or turn rate), **except the divergences Q1 names**, which are + pinned at their probed new values once ruled. Pins the allocator against base. + - `LonginusXDriveAxisEqualsBaseFormula`: a drive-only hull; for every probe input, `AetherDrive.Axis` equals + `(my, mx, sqrt(|sin e|)·sign)` to 1e-3. Pins the live player ship's feel exactly. + - `LonginusMissingCcwReachesHeadingOnDeadSideTheLongWay`: `Th.CCW` destroyed through the real `ItemDamage` + path. Write `LookDirection` directly, as the player would, to 90° left. Heading changes are clockwise every + tick (never CCW), and the ship reaches within 2° in under 1.0 s; the base-rate bound is 270°/394.33°/s = + 0.685 s. Base comparison: error still 90.0° after 30 s. Pins the shared feasible-direction choice. + - `LonginusMissingCcwTurnsRightAsBefore`: looking 90° right reaches within 2° in 0.32 s ± one tick (base + value). Pins that damage on one side leaves the other side alone. + - `LookDirectlyBehindTurns`: intact, look exactly aft. The ship turns, `|Direction|` stays 1 ± 1e-4, and there + is no NaN. Pins the snap's deletion and the >90° profile. + - `ZeroLookHoldsHeading`: default `LookDirection` gives no NaN in `Direction` or any throttle. + - `DestroyedThrusterNeverReceivesThrottle`: for each Djinni thruster in turn, destroy it, then drive 50 + ticks of mixed inputs (forward, strafe, turn both ways, diagonal). Its `Axis` is 0 on every tick. Repeat for + `Enabled = false` and for a zero power grant. Pins invariant 7. + - `RepairedThrusterRejoins`: destroy, restore durability, `UpdatePerformance`. The next tick's strafe uses it. + Pins the live read (invariant 3) against the old permanent pruning. + - `PlayerAndAiInputsGiveIdenticalThrottles`: two identical Djinni hulls with the same damage. One gets inputs + the way `ActionGameManager` writes them (`LookDirection` with nonzero pitch from yaw/pitch Euler, + `MovementDirection` from a stick value). The other gets them through an `Agent` state writing the same yaw, + flat. After `Update`, every actuator throttle is identical. Pins R2. + - `LonginusMissingMainHoldsHeadingUnderThrust`: `Th.L` destroyed, forward input. Heading drift stays under 1° + over 2 s, and forward acceleration is at least 70 m/s² (probe: 78 with 12 lateral slip). Pins torque-coupling + compensation in the shared layer. + - Negative greps, verified against `cd846916` to hit only the lines this cut deletes: + - `\.Axis\s*[-+]?=` in `Assets/Scripts` should match nothing outside `ShipControl.cs`. At base it matches + exactly `Ship.cs:256,264,273,275,276,287,288,291`. `FieldDriver.cs`'s `RectTransform.Axis` does not match; + checked. + - `_forwardThrusters|_clockwiseThrusters|StrafeTorqueThrusters|RecalculateThrust|TurnTime\(` should match only + `ShipControl.cs`'s new `TurnTime`. + - `IAnalogBehavior` should match nothing. + - `lerp\(Direction` in `Ship.cs` should match nothing. + - No least-squares code outside CultMath: `Cholesky|pseudo.?inverse|ActiveSet` in `Assets/Scripts` should + match nothing. + - Stryker: `dotnet stryker --since:` from `tests/Aetheria.Shared.Tests`. Every non-equivalent + survivor in `ShipControl.cs`, `Thruster.cs` and `AetherDrive.cs` is killed or triaged by name. Float boundary + flips are equivalent, per the fire-control Cut 11 ruling. + - Operator: fly LonginusX and confirm it feels unchanged (strafe, turn, look behind now turns). Then fly a + thruster ship, which needs a content hull with `Thruster` hardpoints; until one exists this check is + fixture-only, so say so. +- **Operator questions:** Q1 and Q2, below. +- **Ledger estimate:** −200 lines in `Ship.cs`, −10 elsewhere. `ShipControl.cs` adds about 250–350 lines, tests + about 400. Net source roughly +100. That buys actuator-loss capability, which is the explicit ask, and removes + seven parallel role sets, the snap, and permanent pruning. + +## Cut 3. Heading planner in the AI + +- **Repo/branch:** Aetheria, after Cut 2. +- **First:** pin base AI results as constants. On base, a Djinni with all stern thrusters destroyed never reaches + the target (speed 0 at 120 s). Intact, it reaches it in 4.34 s. Both come from the probe (Agent plus MoveTo, dt + 0.02, target 300 m to port from (37,−12), nose `normalize(0.8,0.6)`). +- **Deletes first:** `Agent.cs:16-17` (the two thresholds) and `Agent.cs:60-78` (the body of `Accelerate`, 19 + lines). `MoveTo.cs:26` (the duplicate `LookDirection` write). The signature `Accelerate(float2, bool noTurn)` + stays, since `Combat.cs:127` and `MoveTo.cs:27` call it. +- **Adds:** in `Agent` (above the inputs, AI only): + - Candidates: 16 evenly spaced headings, plus the Δv direction, plus the current heading. + - Score for each: `TurnTime(θ) + |Δv| / TranslationCapacity(Δv expressed in θ's body frame)`, infinite where + capacity is 0. Both terms come from `ShipControl`'s queries (invariant 8). + - Pick the argmin with hysteresis: replan when a candidate beats the current plan by a margin, and on a cadence + (for example every 0.25 s) or when the actuator set changes. The cadence exists for cost: 18 capacity solves + per replan. + - Write `LookDirection = θ*` unless `noTurn`. Write `MovementDirection` as the per-half-axis fractions that point + the translation demand along Δv, inverting `ShipControl`'s own mapping (a `ShipControl` helper, so the AI never + re-derives it), with a deadband near zero Δv. + - `noTurn` (combat) skips heading choice but still gets capability-correct thrust direction. A Djinni with no + stern facing its target strafes or backs off on its own. +- **Authority map:** + - Owner: `Agent` decides what the AI writes to the two inputs. + - Inputs: target velocity, `ShipControl` capability queries, current velocity and heading. + - Outputs: `LookDirection` (unless `noTurn`) and `MovementDirection`. + - Derived: the plan (heading, time of last replan) is command state only. + - Forbidden writers: `MoveToState` writing `LookDirection`; any AI code writing throttles or `Direction`; any AI + capacity estimate not read from `ShipControl`. + - Shared paths: `MoveToOrbitState` (patrol) and `CombatState` both go through `Accelerate`. +- **Verification:** + - `DjinniWithoutSternReachesTargetByCrabbing`: stern cluster destroyed, target 300 m at a bearing 30° right of + the nose. Driven through `Agent` plus `MoveToState` subclass with a fixed target. The ship arrives within 10 m + in under 8 s, and the planner's chosen heading puts a lateral pair along Δv. Base never arrives. Pins R1(2) and + the stuck-forever cheese. + - `CrabBeatsPointAndBurnWhenMainIsWeak`: Djinni with Stern 1 and Stern 2 destroyed (asymmetric; Stern 3's torque + is balanced by the laterals), target 300 m at 60° left. The planner arrives strictly sooner than a naive + point-and-burn agent run in the same harness through the same Cut 2 allocator. Pins that crab walking wins when + it should, as a relation and not a captured number. + - `IntactShipsStillPointAndBurn`: an intact Djinni picks a heading within 10° of Δv and arrives no later than + base's 4.34 s + 10%. Pins no regression. + - `LonginusWithoutReverseFlipsToBrake`: target velocity opposite the current velocity; the planner turns toward + it (a Longinus has no reverse thrust). + - `PlannerUsesShipControlCapacities`: after destroying a thruster, the planner's turn time for a dead-side + heading equals `ShipControl.TurnTime` for that heading. Pins invariant 8 and the long-way-aware estimate. + - Negative grep: `LookDirection` in `Agents/States/MoveTo.cs` should match nothing. + - Stryker `--since:` over `Agent.cs`, `MoveTo.cs` and `ShipControl.cs` queries. + - Operator: watch a patrol Djinni with a stern thruster shot out crab to its next orbit. +- **Ledger estimate:** −22 lines, +120 lines of source, +250 lines of test. + +## Cut 4. Combat facing and tactics (target shape only) + +This cut gets mapped after fire-control Cut 12 lands, because that cut decides what presenting a side is worth. + +- **Owner:** `CombatState` (`Combat.cs:88-127`), above the inputs. +- **Shape:** choose the orbit side and facing from `ShipControl` capabilities (per-direction rotation authority, + translation capacity along candidate directions) and from weapon arcs. A one-way turner keeps its target drifting + toward its live turn direction. A ship with good turret arcs and poor rotation holds a heading and lets the + turrets work. Weapons with fixed arcs pull the heading onto the target. It uses the Cut 3 planner for thrust. +- **Fork:** Q4 (heading versus aim), which must be ruled before mapping. + +## Operator questions + +Each question gives options and a recommendation. Self paces these one at a time. + +- **Q1: intact-ship divergence from base (blocks Cut 2 pins).** The probe of the stated objective found these + differences on intact ships (new versus base): + - Longinus turning in place also fires a main at 12%, which adds 10.7 m/s² of forward creep (about 6% of full + forward) and cuts lateral slip from 69.0 to 67.3. The L2 objective trades a little slip for a little creep. + - Longinus forward+turn at 30° keeps 164.8 of 172.4 forward (−4%). + - Djinni strafe reaches 37.0 m/s² instead of 34.0 (+9%), by balancing torque with Stern 3 plus Bow. + - Djinni turning bleeds Stern 2 plus Bow at 10% each (zero net force, visible exhaust). + - Turns past 90° now run at full rate instead of slowing to zero at 180°. + + Everything else in the base table matches within 2%, including LonginusX's drive, which matches exactly. + - **A.** Accept these as the allocator's honest optimum and pin base exactly where they coincide. + - **B.** Require exact base behaviour. That means per-thruster role rules in the objective, which is the bucket + machine this campaign deletes. + + **Recommended: A.** The only live ship (LonginusX) is exact under A. The divergences are small, physical, and + arise only on thruster hulls, which the live catalog does not yet carry. +- **Q2: rotation from translation thrusters (blocks Cut 2).** When no thruster above `TorqueFloor` can turn a ship + one way, may the controller turn it that way by differential translation thrust? For a Longinus that is its two + mains: about 78°/s with a forward lurch. + - **A.** No. Rotation authority comes only from thrusters above `TorqueFloor` and drive torque, so a lost attitude + thruster means that direction is gone. + - **B.** Yes, as a slower fallback. + + **Recommended: A**, because it matches the operator's words ("losing an attitude thruster means you can't rotate + that way anymore") and keeps turning from making the ship lurch. Consequence of A: a Longinus with both attitude + thrusters gone cannot turn at all. +- **Q3: Longinus fixture layout (fixture naming only).** Both legacy catalogs author two aft 2×2 thrusters (`Th.L`, + `Th.R`), not the one big thruster the operator remembers. + - **A.** Fixtures follow the data: two mains. + - **B.** Model one centred main. + + **Recommended: A**, with a note that a lost main is itself a test case (`LonginusMissingMainHoldsHeadingUnderThrust`). +- **Q4: heading versus aim (blocks Cut 4 only).** `LookDirection` is both the heading command and the aim, read by + `LockWeapon.cs:94`'s lock cone, guided projectiles, reticle targeting and the tractor beam. Capability-aware + facing wants the AI to hold a heading that is not its aim, and under R2 any split applies to the player too. + - **A.** Add a heading input beside the aim on the shared surface. The player's heading follows the view unless a + player control is added later. + - **B.** Keep one input, and the AI accepts degraded lock cones and missile aim while it manoeuvres. + + **Recommended: A**, decided when Cut 4 is mapped. + +## Subtraction ledger (estimates) + +| Cut | Removed | Added | Dependencies / targets | +|---|---|---|---| +| 1 | 0 | ~200 src + ~150 test (CultLib) | CultMath gains one file; cultmath-unity 0.2.4; Aetheria pin bump | +| 2 | ~210 (`Ship.cs` ~200, `Behaviors.cs` 4, `Entity.cs` 1, setters) | ~300 src + ~400 test | `IAnalogBehavior` removed; no new package, target or authored field | +| 3 | ~22 | ~120 src + ~250 test | none | +| 4 | not mapped | not mapped | not mapped |