Aetheria/docs/aetheria-perfect-machine-map.md

# Aetheria Perfect Machine Map

Date: 2026-06-13

This is the Proprioception and Imagination pass for turning Aetheria from a
Unity project with ancestral cache/network/UI machinery into a coherent
GameCult machine: typed CultCache state, CultMesh networking, and Eve CultUI
surfaces lowered into Unity without JSON or RethinkDB remaining as live
authority.

## Objective

Aetheria should persist and replicate game state as typed CultCache documents,
publish multiplayer/service state through CultMesh, and render operator/runtime
interfaces from Eve CultUI surfaces. The old JSON, RethinkDB, JsonKnownTypes,
legacy catalog cache, and legacy UI paths should be migration-only or deleted.

## Current Mechanism

- Unity client/runtime lives under `Assets/`. Gameplay still reads the legacy
  item/name catalog through a private `ActionGameManager` boot helper, which is
  now the only runtime entrypoint that calls `LegacyCatalogBoundary.GetCatalog`.
  `ActionGameManager` no longer owns a global legacy cache. Local run saves,
  loadouts, player settings files, zone files, and generated keyboard layout
  caches no longer write bespoke durable files. The legacy `PlayerSettings`
  runtime object is no longer decorated as a MessagePack persistence shape.
- Shared domain state is still partly built around `DatabaseEntry`, GUID
  identity, MessagePack attributes, and static cache references. Newtonsoft,
  JsonKnownTypes, RethinkDB, LiteNetLib client transport, and the broken
  `Economy.Shared` wrapper have been removed from live source. The stale
  `StrategyGameManager.csbak` backup file and unused Unity asset MessagePack
  formatter classes have also been deleted, so the remaining direct
  `MessagePackSerializer` calls are the two legacy catalog deserializers and
  their resolver setup.
- Local legacy catalog data remains in `GameData/AetherDB.msgpack` and
  `GameData/NameFile/*.msgpack` as migration/catalog inputs. The old
  `PlayerSettings.msgpack`, `.loadout`, `.zone`, and
  `GameData/KeyboardLayouts/*.msgpack` authority paths are disabled or deleted.
  The old `SavedGame`/`SavedZone` DTOs and `Galaxy` save-loader constructor are
  deleted. The dead `SavedStory` JSON DTO is deleted. `ZonePack`, body/orbit
  zone runtime data, item-instance runtime data, `Ship`, and `EntitySettings`
  remain as runtime construction/loadout/session projections, but no longer
  declare themselves as MessagePack persistence documents.
- `Aetheria.State` now expands `AetheriaPlayerSettings` beyond an active-run
  pointer into the typed Verse replacement for `PlayerSettings.msgpack`: player
  name, tutorial flag, story-file hash cursors, gameplay formatting, graphics
  preferences, input binding overrides, and action-bar inputs. Unity's menu and
  input screens still mutate the old `PlayerSettings` runtime object in memory
  until the runtime Verse package is wired.
- `Aetheria.State` now exposes typed node put/get ports for run state, zone
  state, and entity snapshots. The state smoke writes a run referencing a zone,
  a zone referencing an entity snapshot, and an entity snapshot carrying
  position, direction, faction, hull, equipment slots, weapon groups, and a stat
  grid. This proves the `.zone` replacement graph is durable typed state; Unity
  `ZonePack` and `EntityPack` are still runtime construction projections until
  the runtime package is wired.
- `Aetheria.State` now defines `AetheriaLoadoutTemplate` as the typed Verse
  replacement for bespoke `.loadout` files. It stores structured hull,
  equipment, cargo bay, docking bay, child-entity, assignment, and weapon-group
  state through record-key references and typed value slots instead of opaque
  `EntityPack` serialization. Unity has not wired its save/loadout UI to this
  document yet, so the old in-memory `EntityPack` path is still a runtime
  construction helper, not durable authority.
- The private `ActionGameManager` catalog boot helper delegates to
  `LegacyCatalogBoundary`, which opens `LegacyCatalogCache` as the only
  concrete pull-only catalog cache. Runtime consumers receive
  `ILegacyCatalogReader`, so old MessagePack backing stores may hydrate
  in-memory domain objects for the current Unity runtime, but this path cannot
  push or delete legacy files. The legacy backing-store
  write/realtime APIs and public cache mutation methods have been deleted; only
  backing-store pull hydration can populate it. The backing-store serializer
  methods are also deleted, so the legacy cache implementation exposes
  deserialization only. UI code no longer reaches into
  `LegacyCatalogBoundary.GetCatalog` directly.
- `ItemManager` no longer exposes the raw `ILegacyCatalogReader` as public
  gameplay/UI API. Item, faction, loadout, trade, and entity restore consumers
  now go through narrow `ItemManager.GetCatalogEntry<T>` and
  `GetCatalogEntries<T>` methods. This does not remove the legacy reader under
  the hood; it prevents old catalog authority from leaking into every caller
  that only needs a domain lookup.
- `Galaxy` generation no longer accepts `ILegacyCatalogReader`. Sector and
  tutorial generation receive `ItemManager` and use the same narrow catalog
  lookup port for factions and name files. `ActionGameManager` now has a
  private legacy catalog boot helper that feeds only `ItemManager`;
  menu/generation paths no longer receive the legacy reader directly.
- `DatabaseLink<T>.Value` can resolve legacy links only after
  `LegacyCatalogBoundary` binds the pull-only catalog cache. Legacy catalog
  construction no longer grabs global `DatabaseLinkBase` authority.
- `Economy.Server` now starts the modern `Aetheria.State` CultMesh node and no
  longer owns RethinkDB/LiteNetLib state.
- `Aetheria.State.Import` writes a typed quarantine manifest and migration
  ledger for the legacy catalog files. It also raw-decodes stable old
  MessagePack union fields into typed item/faction/name-file documents without
  compiling the old Unity domain model into `Aetheria.State`. The current
  checked-in catalog maps to 115 item definitions, 12 factions, and 12 name
  files. Item definitions now carry legacy manufacturer IDs, price, shape
  dimensions, occupied cell counts, full typed shape-cell masks, hardpoint
  type, hull type, interior shape masks for hull/cargo equipment, hull
  hardpoint definitions, behavior kind fingerprints, typed recursive behavior
  payloads, stack size, durability, and weapon range/caliber/type/fire/modifier
  classifications. Corporation documents now carry the legacy short name, true
  description from key 3, name-file and boss-hull legacy IDs, influence
  distance, allegiance count, and music bank IDs. Empty legacy GUID references
  are imported as absent links rather than as `Guid.Empty` catalog IDs.
  `Aetheria.State` now owns the canonical legacy-ID record key mapping for
  migrated item, corporation, and name-file documents.
- `AetheriaCatalogSnapshot` is the typed catalog read surface over materialized
  `.cc` records. It exposes trade-item, manufacturer, corporation prefix, and
  corporation name-file queries, plus equipment, hardpoint, and behavior
  queries without touching `DatabaseEntry`.
- `Aetheria.State.Unity` is the Unity-facing runtime read facade over typed
  catalog state. It opens `aetheria-world.cc`, emits immutable catalog read
  models for trade/equipment/behavior/hardpoint/manufacturer/corporation/name
  queries, exposes typed item shape masks for layout/fitting consumers, and
  exposes typed interior masks and hardpoints for future equipment/cargo
  layout consumers, plus typed behavior payload read models for future
  behavior factories. It reads the published Eve surface without deserializing
  legacy `DatabaseEntry` objects. It is not a simulation owner and does not
  write state.
- `AetheriaCatalogSurfaceProjector` now emits the first provider-owned Eve
  surface from typed catalog state. The importer materializes a
  `gamecult.eve.surface.v1` catalog operator document at
  `eve:surface:aetheria.catalog.operator` with summary, trade-catalog, and
  corporation views. This is a typed CultCache surface document, not a renderer
  dashboard or JSON status card.
- `GameData/aetheria-world.cc` is now materialized from the importer as the
  project-local typed state file for the checked-in catalog. The importer stores
  relative provenance in the state document, not machine-local absolute paths.
  Import rebuilds clear the generated `.cc`, `.cc.records`, and `.cultmesh`
  outputs for the selected state path after capturing legacy inputs, so schema
  evolution can rematerialize typed state instead of being blocked by stale
  embedded schema catalogs.
  `Aetheria.State.Verify` opens the materialized file and checks that migration
  ledger counts match actual typed catalog records, that the legacy-ID lookup
  API resolves migrated item, corporation, and name-file documents, and that
  the expanded typed catalog facts, typed catalog snapshot queries, and typed
  Eve catalog surface are present in the `.cc` store. The current verifier sees
  52 shaped item masks, 5 interior masks, 3 hardpoint-host hulls, 22
  hardpoints, 39 behavior-bearing item definitions, 65 behavior payloads, 661
  behavior fields, 18 behavior-side legacy-ID references, 51 hardpoint-tagged
  equipment items, 3 hull items, and 18 weapon-facet item definitions. Legacy
  content includes at least one overhanging hardpoint (`LonginusX`); migration
  verification preserves that payload and does not convert content repair into
  mapper authority.
- `.voidbot/state/aetheria.cc` is the repo Persona state witness. Aetheria is
  not registered as a VoidBot Discord identity yet, so mutations use the
  repo-local `void-self-state.mjs apply-operation` typed boundary rather than
  the registered Face MCP path.
- The old IMGUI DB inspector under `Assets/Scripts/CultCache/Editor/` has been
  deleted. `NameTools` can still clean/generate names, but legacy NameFile
  `.msgpack` export is disabled.
- MessagePack is no longer used as a runtime object-cloning shortcut for
  `EntitySettings`, and UI/player-settings startup no longer registers the old
  MessagePack resolver. Resolver registration is confined to legacy catalog
  deserialization. Unused Unity asset formatters for GameObject, Material,
  Sprite, and Texture2D are deleted. Keyboard layout DTOs are plain runtime
  parse/display models, not MessagePack save shapes. `PlayerSettings` is a
  plain session-local runtime object until typed Verse settings are imported
  into Unity. `ZoneData` body/orbit DTOs, `ItemInstance` DTOs,
  `EntitySettings`, `Ship`, Unity inspector game settings, environment/volume
  settings, exponential curves, Wwise bindings, and enum dictionaries are also
  plain runtime/session/config projections now, not MessagePack persistence
  shapes. The global scene-load MessagePack resolver hook is deleted. The slime
  compute settings path no longer serializes its local parameter struct for
  change detection.
- The dead story compiled-JSON cache sketch and its SHA helper are deleted;
  story compilation currently reads Ink source directly until a typed Verse
  story/cache document exists.
- Runtime UI is old Unity UI/uGUI prefabs plus `MonoBehaviour` scripts under
  `Assets/Scripts/UI/` and `Assets/Prefabs/UI/`.
- Aetheria already has Unity UIElements support available through
  `com.unity.modules.uielements`, but no imported Eve Unity lowering package.

## Invariants

- Durable game state is typed CultCache state, not JSON documents or ad hoc
  sidecars.
- Network-visible state is published through CultMesh/CultNet documents, not a
  RethinkDB changefeed or bespoke status endpoint.
- Record identity belongs to CultCache record keys and typed references, not to
  mutable domain base classes.
- UI surfaces are provider-owned Eve CultUI documents; Unity is a lowering
  runtime, not the owner of UI truth.
- Migration code may read old formats, but old stores cannot decide live state
  after migration.
- The runtime must have one commit path for user action, load/import, server
  replication, and editor mutation of the same state.

## Current Authority Map

- Owner: `Aetheria.State` owns the new typed state spine for durable state.
  `LegacyCatalogBoundary` is the only named owner for opening the old catalog
  and binding legacy `DatabaseLink<T>` resolution until catalog migration lands.
  `ActionGameManager` has a private boot helper that calls it only to construct
  `ItemManager`. Runtime code receives narrow `ItemManager` catalog methods
  where gameplay only needs lookups. `ItemManager` still receives
  `ILegacyCatalogReader` until typed runtime catalog boot replaces it; `Galaxy`
  has been moved off the legacy reader and now consumes `ItemManager`.
  `Aetheria.State.Unity` owns a read-only typed catalog facade for future Unity
  consumers; it does not write state or own simulation. The legacy cache no
  longer has a public mutation surface.
- Inputs: Unity gameplay code, legacy catalog files, typed state documents, and
  CultMesh server state.
- Outputs: `Aetheria.State` emits `.cc` state and CultMesh documents. Legacy
  catalog reads emit in-memory domain objects only; the old local save and
  editor catalog write paths have been cut. Migrated catalog documents are
  addressed through `AetheriaCatalogKeys` and `AetheriaStateNode` legacy-ID
  methods, not importer-local string concatenation. Player settings and loadout
  templates have typed state documents and node put/get paths; Unity's menu,
  input screens, and save button still need to call them through the runtime
  Verse package. Run, zone, and entity snapshot state also have typed node
  put/get paths; Unity `SaveState`/`SaveZone` still need to commit through those
  ports. The catalog operator UI is emitted as a typed Eve surface document
  derived from the catalog snapshot.
- Derived state: UI panels, generated keyboard layouts, editor rows, and
  serialized legacy payloads are projections, migration inputs, or disabled
  session-local DTOs, not durable authority.
- Forbidden writers: old JSON backing stores, JsonKnownTypes converters,
  Rethink/LiteNet paths, IMGUI database editor exports, local save-file writes,
  generated keyboard layout caches, and server-side `DatabaseCache` paths.
- Shared paths: manual gameplay edits, editor edits, server updates, file load,
  file save, and migration all need to converge on one typed commit primitive.
- Deletion line: no new behavior should be added to `LegacyCatalogBoundary`, the
  old `DatabaseEntry`, `LegacyCatalogCache`, or MessagePack catalog paths
  except bounded migration readers that emit typed `Aetheria.State` documents.

## Target Authority Map

- Owner: `Aetheria.State`, a typed document layer backed by modern
  `GameCult.Caching` and opened through a CultMesh node.
- Inputs: typed commands, save/import migration records, CultMesh replication,
  editor mutations, and deterministic simulation facts.
- Outputs: CultCache `.cc` state files, CultMesh document streams, Eve surface
  documents, simulation events, and migration reports.
- Derived state: Unity scene objects, HUD panels, editor inspectors, debug
  views, server dashboards, and compatibility DTOs.
- Forbidden writers: Unity UI components, RethinkDB, legacy JSON stores,
  `DatabaseEntry.ID`, global cache statics, and any compatibility reader.
- Shared paths: gameplay input, editor edits, import/deep-load, replication,
  simulation ticks, and tests all call the same typed state service.
- Deletion line: after catalog migration smokes pass, replace
  `ActionGameManager`'s private legacy catalog boot helper and `ItemManager`
  boot with the typed runtime catalog package, then delete or quarantine the
  remaining `LegacyCatalogCache`/`DatabaseEntry` runtime catalog dependency and
  remove old MessagePack backing store classes from live Unity source.

## Intended Change

Create a modern Aetheria state runtime that opens a CultMesh node over a typed
CultCache file, registers Aetheria document types, and exposes narrow ports for
gameplay, editor tools, migration, and UI projection. The state runtime becomes
the only live writer. Everything else becomes a consumer, a command source, or
a migration reader.

Use modern CultLib surfaces:

- `GameCult.Caching` for `[CultDocument]`, record keys, indexes, references,
  schema catalog, and typed persistence.
- `GameCult.Caching.MessagePack` for the binary CultCache backing format.
- `GameCult.Mesh` for node/database illusion, durable shard logs, Verse
  descriptors, authority leases, replication, and peer discovery.
- Eve CultUI for portable UI documents and command envelopes.

## UI Direction

Unity should lower Eve surfaces through UI Toolkit, not through the old uGUI
CultUI package as the strategic path.

The package should live in the Eve repo as an importable Unity package, for
example `org.gamecult.eve.unity-uitoolkit`. It should consume
`gamecult.eve.surface.v1` and `gamecult.eve.command.v1`, lower retained
components into `UIDocument`/`VisualElement` trees, and publish commands back to
the provider through CultMesh/CultNet.

Aetheria should import that Eve package and provide surfaces. It should not own
a bespoke Unity lowering. The existing CultLib Unity uGUI package remains useful
as prior art for resolver-backed controls and inspector generation, but it is
not the new portable UI authority.

Until that shared Eve package exists, Aetheria publishes provider surfaces as
typed CultCache documents using a local mirror of `gamecult.eve.surface.v1`.
The mirror is not a new UI authority; it is the state provider contract that a
future Eve package should replace or align with.

First Aetheria surfaces to publish:

- runtime HUD
- inventory
- menu shell
- sector/map view
- typed state inspector
- migration report / quarantine viewer
- server/session status

## Migration Phases

1. Baseline
   - Record the current compile/test status for Unity and .NET projects.
   - Keep this map current before cutting code.
   - Count old authority references with `rg` so deletion has a visible target.

2. Modern state spine
   - Add references to modern `GameCult.Caching`,
     `GameCult.Caching.MessagePack`, and `GameCult.Mesh`.
   - Create `Aetheria.State` document definitions using `[CultDocument]`,
     `[MessagePackObject]`, `[CultName]`, `[CultIndex]`, and typed references.
   - Add a smoke that writes, flushes, reopens, and reads typed state from a
     CultCache `.cc` file.

3. Legacy quarantine
   - Done: capture old `GameData/AetherDB.msgpack` and related name files as a
     typed quarantine manifest without granting them runtime authority.
   - Done: emit typed CultCache records plus a migration ledger for the catalog
     quarantine preflight.
   - Done: implement a bounded raw payload mapper that converts stable old
     `DatabaseEntry` union fields into typed item/faction/name-file catalog
     documents without making `Aetheria.State` depend on Unity's legacy model.
   - Done: expand the stable item mapper to include equipment facets and
     behavior kind fingerprints needed by future Unity/Eve catalog consumers.
   - Done: import full item shape-cell masks into typed catalog documents and
     expose them through the Unity-facing read facade.
   - Done: import typed interior shape masks and hull hardpoint definitions
     needed by future equipment/cargo layout and fitting consumers.
   - Done: import recursive typed behavior payloads so future behavior
     factories no longer have to depend on legacy `BehaviorData` objects just
     to see authored behavior fields.
   - Done: expand typed `AetheriaPlayerSettings` so `PlayerSettings.msgpack`
     no longer lacks a durable Verse replacement for actual runtime settings
     values.
   - Done: add typed `AetheriaLoadoutTemplate` documents and smoke coverage so
     `.loadout` no longer lacks a durable Verse replacement.
   - Done: add typed node ports and smoke coverage for run -> zone -> entity
     snapshots so `.zone` no longer lacks a durable Verse replacement graph.
   - Remaining: add typed documents/mappers for runtime object graphs,
     typed behavior factory construction, simulation state, and any catalog
     fields not covered by the stable scalar/fingerprint/payload pass.

4. Runtime cutover
   - Done: add a Unity-facing typed catalog read facade and smoke proving it can
     read the materialized `.cc` catalog plus Eve surface without the legacy
     catalog reader.
   - Replace `ActionGameManager` cache bootstrap with the new state runtime.
   - Convert domain references from GUID/base-class patterns to typed record
     refs.
   - Remove runtime dependency on `LegacyCatalogCache` and `DatabaseEntry` as
     owners.

5. Mesh host
   - Replace `Economy.Server` RethinkDB and LiteNetLib database authority with a
     CultMesh node.
   - Keep any transport bridge only if it delegates to CultMesh and protects a
     named external compatibility contract.
   - Publish Verse descriptors and state subscriptions through CultMesh.

6. Eve UI
   - Done: publish the typed catalog operator surface from `Aetheria.State`.
   - Build or import the Eve UI Toolkit lowering package from the Eve repo.
   - Replace the old IMGUI DB inspector first, because it is closest to state
     authority.
   - Then replace runtime HUD/menu/inventory/map screens.

7. Purge
   - Done: delete vendored RethinkDB.
   - Done: delete JsonKnownTypes.
   - Done: delete Newtonsoft dependencies and attributes from live code.
   - Done: delete old JSON backing stores.
   - Done: delete the broken `Economy.Shared` wrapper and tracked build output.
   - Done: disable legacy local save, loadout, zone, player-settings, keyboard
     layout, DB inspector, and NameFile export writers.
   - Done: delete the old `SavedGame`/`SavedZone` runtime save DTO and loader.
   - Done: stop legacy catalog pull/read paths from writing entries back to
     their source backing store.
   - Done: delete legacy catalog backing-store write/realtime APIs.
   - Done: delete public legacy catalog cache mutation APIs.
   - Done: delete the stale `StrategyGameManager.csbak` backup source and
     unused Unity asset MessagePack formatters.
   - Done: demote keyboard layout DTOs from MessagePack shapes and delete the
     global scene-load MessagePack resolver hook.
   - Done: demote `PlayerSettings` and nested settings from MessagePack shapes
     after the legacy settings writer was disabled.
   - Remaining: delete or quarantine old cache abstractions that no longer
     protect an invariant once catalog migration has a typed reader.

## Verification

- `rg "Newtonsoft|JsonObject|JsonProperty|JsonConvert|JsonKnownTypes|RethinkDb|RethinkTable|DatabaseCache"` is zero outside migration quarantine and docs.
- `rg "DatabaseEntry" Assets Economy.*` shows no live runtime ownership path.
- `dotnet list package --vulnerable --include-transitive` is clean for active
  maintained projects.
- CultCache smoke proves write, flush, reopen, query, and typed reference
  resolution, including full player settings as the `PlayerSettings.msgpack`
  replacement, loadout templates as the `.loadout` replacement, and a run ->
  zone -> entity snapshot graph as the `.zone` replacement.
- CultMesh smoke proves node start, typed put/get, subscription, flush, and
  reopen.
- Eve surface smoke proves provider-owned surface documents are generated from
  typed state and survive `.cc` store reopen before any renderer owns them.
- Quarantine import smoke proves old catalog file facts can be captured into
  typed state without old readers remaining on the live runtime path.
- Migration smoke proves stable old catalog payload fields can be read once and
  converted without old readers remaining on the live runtime path.
- Unity runtime catalog smoke proves read-only catalog consumers can open the
  typed `.cc` store through `Aetheria.State.Unity` without `DatabaseEntry` or
  `LegacyCatalogCache`, including typed item masks, interior masks, and
  hardpoint definitions, plus typed behavior payloads.
- Unity play smoke proves runtime UI reads from Eve surfaces and sends commands
  through the shared state service.
- UI Toolkit lowering parity compares Aetheria surfaces against the Eve browser
  renderer for component tree, state bindings, command envelopes, disabled/stale
  states, and visible error surfaces.

## Immediate Cut Line

Do not bump Newtonsoft as the fix. That keeps the wrong organ alive with newer
paint on it.

The first implementation cut should create the modern typed state spine and a
legacy quarantine. After that, every RethinkDB/Newtonsoft/JsonKnownTypes removal
has somewhere clean to land, and every old path can be judged by whether it
still owns behavior.