Aetheria/docs/original-game-migration-matrix.md
2026-07-12 00:19:03 +01:00

141 lines
16 KiB
Markdown

# Original Game To Perfect Machine Matrix
Status dimensions:
- `reference`: behavior exists only in the fossil/reference implementation;
- `owner-exists`: target subsystem implements the primitive in isolation;
- `wired`: production Aetheria paths invoke that owner;
- `exclusive`: obsolete writers cannot decide or repair the result;
- `projected`: authoritative state reaches Eve;
- `lowered`: a generic runtime presents or controls it;
- `proven`: live parity and negative-authority checks pass.
Dimensions are cumulative claims only when evidence proves each one. Fixture
validation proves contract shape, not wiring, exclusivity, lowering, or parity.
| Organ | Original authority/evidence | Target owner | Eve contract | Runtime lowering | Current status | Required proof |
|---|---|---|---|---|---|---|
| Run/session state | `ServerShared`, `ActionGameManager` | Aetheria daemon/CultCache | provider/session advertisement | all clients | owner-exists; wired; projected; not proven | restart and multi-client convergence |
| Entity identity/loadout | `ServerShared/Entity*` | daemon | typed entity and inventory surfaces | EveUnity/Electron | owner-exists; wired; projected; not proven | loadout round trip and reconnect |
| Loadout generation | map/faction availability, item cost, hull hardpoints and role constraints | daemon using canonical galaxy, faction knowledge/economy and typed catalog | generated loadout plus provenance/availability facts | Eve inspection and refit surfaces | daemon now uses the fossil candidate filter and seeded weighted selection: manufacturer must be present and allied, ally weight decays by home-zone graph distance, price uses the authored exponent, hardpoints require exact type/cell/rotation fit and controller role, and cargo/capacitor plus station docking equipment must fit remaining hull space; stations draw up to sixteen faction-available equipment rows and pack largest-first into the selected cargo bay's actual interior shape; zone generation derives one continuing deterministic RNG stream per availability corporation, so cross-faction calls cannot perturb another faction; every generated entity persists an immutable source/selection receipt that reaches Eve as `loadout.item` semantics; Terminus explicitly maps combat-role factions to catalog availability corporations | multi-zone generated-world parity and exact root-to-zone stream sequencing against the fossil |
| Flight intent | `Ship`, `Thruster`, `AetherDrive`, input paths | daemon intent + Ymir physics | analog movement/look/tractor | EveUnity input driver | movement intents feed Ymir-owned body integration; authored thrust allocation, torque, energy and heat remain simplified | prove original drive/equipment behavior ordering and runtime interpolation |
| Collision | Unity physics and entity handlers | Ymir | collision/result facts | visual interpolation only | Ymir.Core world stepping wired for entity bodies, radial fields and contacts; missing-owner negative proof passes | publish authoritative collision events and prove Unity cannot write transforms back |
| Targeting/contacts | sensors + `ActionGameManager` | daemon | contact/target semantics | target HUD and indicators | simplified owner wired/projected; daemon weapon lock now acquires and decays from facing, elapsed time, and observer-local contact confidence instead of granting an immediate perfect lock | target-switch reset, angular decay, visibility/nearest/explicit cases, and runtime lock feedback |
| Projectile flight | weapon/projectile classes | Ymir | projectile entity/event projection | native projectile visual | Ymir.Core adapter wired for spawn/travel/contact/despawn; native presentation and broader weapon parity incomplete | prove every authored projectile family and runtime visual lifecycle |
| Shield/hull damage | energy-funded shield, armor cells, equipment and hull | daemon | entity status + damage events | meters, impacts, damage VFX | synthetic scalar owner wired; not parity | typed absorption, penetration, item damage and death causes |
| Thermal/energy | cell conduction and capacitor/reactor/radiator network | daemon | ship/equipment status and warnings | schematic/post effects | cell conduction/radiation wired; energy network and medical thresholds remain reference | capacitor/reactor/radiator ordering, shared energy and medical timelines |
| Weapons | ServerShared behaviors + Unity effects | daemon + Ymir where spatial | action capability, weapon state, attack events | effects/audio/HUD | selected weapon groups resolve equipped typed-catalog behaviors for damage, range, cooldown, projectile velocity, heat, lock, energy, magazine, reload, burst count/time and single-ammo-burst parameters; persistent burst timer/remaining state emits every due round while cooldown overlaps from trigger time; damage/heat/energy divide across rounds and resource payment occurs once per burst or once per round as authored; each committed transaction drains canonical capacitor/reactor state and magazine before Ymir launch; empty magazines consume reserve cargo through the shared cargo transaction and enter reload without firing; catalog-free fixtures retain an explicit synthetic fallback | strict reload/cooldown boundary timeline, visibility/wear, and each remaining weapon family |
| Destruction/drops | entity death and pickup paths | daemon | death/drop events and world entities | effects and pickups | fragments wired; chronology and original drop transaction absent | exactly-once drops and cleanup |
| Tractor/scoop | analog tractor and physical timed pickups | daemon + Ymir | tractor power, pickup body and receipt | beam/interaction feedback | fossil 2/s power ramp and authored forward radius/traction/distance feed pickup bodies into the shared Ymir world; shield contact collects exactly once when capacity permits or applies the fossil 25-unit rejection kick; 30s daemon lifetime; instant cargo teleport deleted | prove generic runtime beam, contact, success and rejection feedback |
| Dock/undock | wormhole-first interact; first eligible bay; component prerequisites | daemon + Ymir placement | dock commands/context | camera/UI transition | daemon path wired/projected; Ymir placement and parity unproven | priority, eligibility, placement and reconnect |
| Inventory/equipment | inventory panels + ServerShared | daemon | inventory/equipment surfaces | generic UI | owner-exists; wired/projected in fragments; not proven | all transfer directions and rejection |
| Trade | trade UI/economy | daemon | stock, quote, purchase commands | generic UI | purchase owner wired/projected; not proven | atomic purchase and capacity |
| Action bar/input | input shell and rebinding UI | daemon advertises actions; client owns bindings | input capability and action descriptors | universal binding UI | contracts wired; dynamic original behavior source absent | dynamic equipment/cargo actions |
| Pilot camera | ARPG follow/dock cameras | Eve view semantics + runtime | camera rig and semantic view id | EveUnity camera rig | basic follow lowered; dock/view parity absent | authored framing and dock transition |
| Render channels | Unity layers/culling masks | provider variant + runtime | semantic view id | native layer policy | specification work; incomplete uncommitted prototype | no map glyphs in pilot view |
| Minimap/tactical map | `ZoneRenderer`, map cameras | daemon world facts | explicit map projections | Unity and Electron | facts fragmented; generic lowerers absent | same state in both runtimes |
| Fields/fog/gravity | zone renderer and shaders | daemon/plugin semantics | Fields plugin documents | EveUnity fields lowerer | owner-exists; basic lowering; composition parity absent | visual parity captures |
| HUD/schematic | ARPG HUD and `SchematicDisplay` | Eve composition from daemon facts | semantic status/components | EveUnity UI | reference | source-fact and timing matrix |
| Hit/lock/warnings | `ActionGameManager` feedback | daemon event facts | transient feedback stream | VFX/UI/audio | bounded deduplicated game-event ledger and Eve `feedback.stream` wired for pickup outcomes, projectile launch/impact, entity damage, alive-to-dead destruction, authoritative weapon reload chronology, and episode-deduplicated `weapon.fire.refused` facts for insufficient energy or missing ammunition; refusal identity, authored weapon, target, reason, and remaining magazine state are runtime-independent cockpit inputs | add lock transitions, thermal and docking event families, negative transaction fixtures, and runtime effect consumption |
| Assets | `Assets/Resources` | Aetheria provider | asset catalog + CultMesh CDN | runtime cache/load | wired; basic lowering; not live-proven remotely | cold/warm remote-only live load and cache proof |
| Save/resume | original persistence paths | daemon/CultCache | published current state | clients rehydrate | owner-exists; not parity-proven | mid-loop restart |
| Terminus loop | original game composition | daemon/Ymir/Eve | pilot surface | Aetheria.Unity | incomplete; no scenario proof | fly/fire/loot/dock/trade |
| Starbridge | original/shared architecture intent | one daemon session | pilot + commander surfaces | Unity + Electron | commander task board and autonomous explore execution wired; Electron Eve lowering and split-target proof missing | commander orders plus four pilots and autonomous workers |
| Behavior engine | `ServerShared/Behaviors` composition | daemon | executable action/status projection | action bar and feedback | tick reconciles equipped catalog payloads into persistent behavior state; shared evaluated-stat query proven; execution families remain partial | every behavior family, ordering, resource transaction and modifier lifecycle |
| Sensors/visibility | decaying sources and observer information thresholds | daemon | contacts and ping events | indicators/maps | reference | threshold, decay, ping and classification timelines |
| AI/tasks | corporation task scheduler plus agent state machines | daemon | commander task board, corporation survey ledger, and shared semantic controls | Eve commander/pilot clients | point exploration, attack with optimum-range control, same-zone haul, mining/offload, resource surveying, physical station towing, persistent orbit patrol, route-aware assignment, and autonomous return home wired through shared commands; attack admission rejects missing/friendly targets and unavailable weapon groups before durable queueing; capability/priority assignment and rejection behavior proven; generic Electron commander lowering proves the worker roster | cross-zone logistics execution, cancellation, reconnect, and multi-client command transfer |
| Consumables | cargo-backed timed behavior containers | daemon | dynamic actions and active effects | action bar/schematic | reference | consume, stacking, duration and cleanup |
## Ownership Invariants
1. Unity objects never decide durable game state.
2. Target invariant: Ymir will own spatial truth; the daemon owns game meaning
and persistence. Current state: Aetheria still owns multiple local spatial
implementations.
3. Eve publishes semantic facts and commands, not Aetheria implementation
objects or runtime-specific layer numbers.
4. Runtime-specific asset metadata may map semantic view channels to native
mechanisms such as Unity layers.
5. Provider assets own authored visuals; EveUnity owns generic projection and
native hosting; Aetheria.Unity owns only provider client configuration.
6. Transient feedback has authoritative event identity so reconnect and refresh
cannot duplicate hits, drops, purchases, or deaths.
7. RTS, minimap, and pilot views are projections of one world state.
8. Restored agent combat and future pilot cognition share semantic ship actions,
command validation, and Ymir execution. They do not share an implicit combat
authority: RTS task scheduling assigns work, while pilot cognition proposes
actions from observer-local knowledge under daemon-owned doctrine.
## Migration Order
1. Finish archaeology and replace every `reference` row with exact behavior,
source anchors, state inputs, outputs, timing, and proof cases.
2. Establish complete daemon/Ymir simulation parity before polishing clients.
3. Publish combat, thermal, contact, equipment, docking, trade, and feedback
facts through Eve without runtime-specific leakage.
4. Implement generic EveUnity presentation primitives and plugin lowering.
5. Reconstruct Aetheria's authored composition in `Aetheria.Unity` using those
generic primitives and provider assets.
6. Run scenario parity against the fossil and preserve captures, receipts, and
state timelines in conformance packs.
Original-game parity is the substrate, not the final pilot command model. New
combat work must follow `cockpit-doctrine-combat.md`: preserve semantic weapon
actions and physical constraints, then place daemon-hosted cognition planning
above them. The planner may propose sensing, maneuver, and fire-control actions;
the daemon command gate alone accepts them, and Ymir alone resolves spatial
motion and collision. Do not spend migration effort rebuilding manual aiming as
the primary skill test or let a Unity presentation path become a second combat
owner.
## Current P0 Faults
These are source-confirmed ownership failures, not feature backlog:
1. **Physics delegation is incomplete.** Daemon projectile and entity-world
integration now use `Ymir.Core`, including radial fields and body contacts,
but tractor forces, docking placement, authored drive torque, and the Unity
bridge/query path still need full authority and parity proofs.
2. **Persisted behavior is not executable behavior.** Snapshot schemas preserve
broad equipment/behavior state while active simulation executes one
synthetic projectile weapon and simplified raider pursuit.
3. **Client feedback chronology is incomplete.** Pickup collection, rejection,
expiry, projectile launch/impact, damage, and destruction now use a bounded
deduplicated daemon ledger projected through Eve, but lock transitions,
damage topology, thermal warnings, and docking effects still need event families.
4. **View composition is implicit.** Provider prefabs contain pilot and map
subviews, but portable render channels, entity presentation graphs, effects,
attachment sockets, and map products are not yet first-class contracts.
5. **The game loop has no single daemon owner.** Exploration, discovery,
encounter, loot, docking, trade, refit, narrative, boss progression,
completion, failure, and continue exist as pieces rather than one explicit
run-state machine.
6. **Unity spatial feedback remains insufficiently fenced.** The daemon now
requires Ymir for world advancement, but the Unity bridge/query path still
needs a negative proof that presentation transforms cannot write spatial
truth back into provider state.
7. **Live conformance has no complete owner.** Static provider packs can pass
while daemon, runtime, or split-target dependencies are absent. The current
Eve consumer smoke fails because its expected EveElectron proof is missing.
8. **Normative native presentation has no implemented owner.** Render channels,
presentation graphs, map products, attachment/effect lifecycles, material
profiles, and source-version diagnostics are assigned in specification but
lack complete Eve contracts and EveUnity lowerers.
9. **Original-game acceptance lacks an evidence ledger.** No current owner
records fossil baseline, target state timeline, commands/receipts, rendered
captures, and negative-writer checks as one scenario result.
## Evidence Rules
- Static fixtures and provider packs prove schema/contract shape only.
- `wired`, `exclusive`, `lowered`, and `proven` require live executable
witnesses at the claimed layer.
- A negative ownership claim must verify the obsolete path cannot produce,
override, or repair the result.
- The current `verify-aetheria-ymir-cutover.ps1` proves selected Unity callback
removal and static routing into an Aetheria bridge. It is not Ymir integration
proof until it verifies an actual Ymir.Core/service dependency and rejects
Aetheria-local spatial implementations.
- Conformance scenarios must preserve source baseline, authoritative state
timeline, Ymir timeline, command/receipt chronology, rendered capture,
runtime/package versions, and negative-authority results together.