Aetheria/docs/cultcache-migration-target.md

CultCache Migration Target

Date: 2026-09-12

Status: landed; awaiting operator play smoke. Aetheria runs on CultLib's CultCache and CultMath, cut over on codex/cultcache-cutover from Cut 8a (4f4beb0f) through Cut 10 (4a545469 to the commit that set this status). The means are in docs/cultcache-migration-cut.md.

Aetheria moves off its in-tree CultCache, the ancestor of the one in CultLib, onto modern CultCache in F:\Projects\CultLib. Adopting the infrastructure the rest of GameCult maintains replaces a private copy with a shared one. This document states the end state and the invariants that constrain getting there.

This touches the foundation

CultNet is built on CultCache, and CultMesh on CultNet. Every CultLib change below lands under all GameCult infrastructure, not just Aetheria.

• Wire parity is an invariant. CultCache maintains wire parity with the other runtimes, and only the packages inside CultLib are canonical: CultLib\packages\cultcache-{py,rs,ts}, cultnet-{py,rs,ts}, and cultmesh-{browser,kotlin,py,rs,ts}. The neighboring repositories F:\Projects\cultcache-rs, cultcache-py, cultnet-rs, and cultnet-ts are defunct and are not parity targets. A change that alters bytes on disk or on the wire must land in every canonical runtime, or it does not land.
• C# is the reference runtime. The ergonomics arose there; the other runtimes follow its contract. Contract changes are written down in CultLib\src\GameCult.Caching\Contracts\ first.
• Existing consumers must survive. Aquarium and Ymir build against CultLib main; other consumers pin revisions or carry copies. AetheriaEve is not a consumer: it is preserved as a specimen and receives no consideration.

Why the previous attempt failed

The first migration (rolled back by 7006a6b0, plan in aetheria-perfect-machine-map.md) made the cache move phase 2 of seven, bundled with an Aetheria.State service layer, CultMesh hosting, Eve UI, and an Electron RTS client. The cache never finished moving. This migration moves the cache and nothing else.

Target state: Aetheria

• All persistent state is CultCache state, split by lifecycle into routed stores inside one cache:

  Store	Holds	Written by	Lifetime
  Catalog GameData/Aetheria.cc	Items, factions, products, name files, other authored records	CultCache Studio	Read-only at runtime
  Run .cc	Galaxy, zones, bodies, orbits, entities, tasks	The run save path	Deleted on death
  Player .cc	Settings, bindings, account	The game	Persists across runs

• Documents versus values. A record with identity that something references or that changes independently is a [CultDocument]. Values without identity (item instances in cargo, behavior lists on a design, weapon groups) live inside their owning document and keep their MessagePack [Union]s.

• References are CultRecordRef<T>, resolved through an explicit cache. DatabaseLink<T>, the static DatabaseLinkBase.Cache, DatabaseEntry, its union, and DatabaseEntry.ID are gone. A catalog record's identity is its record key, which carries the legacy Guid string.

• The live simulation owns in-play state. Entity and its reactive fields are not documents. Quit and zone transition share one save commit (RunSave.Capture then RunSave.Commit); death deletes the run with RunSave.Clear.

• No legacy reader exists. The catalog records carry legacy Guid keys and slot numbers from the one-time import; the importer and the legacy files are deleted.

• Existing saves are discarded. No save converter.

• Deleted from Aetheria: Assets/Scripts/ServerShared/CultCache/, the vendored Assets/Plugins/MessagePack, vendored JsonKnownTypes, the legacy Guid/Type resolvers, and the IMGUI Database Tools under Assets/Scripts/CultCache/Editor/.

• Consumption. Unity takes the full org.gamecult.cultlib UPM package pinned by git tag. Aetheria.Shared/Aetheria.Shared.csproj references the same CultLib version, so the headless build still proves the simulation compiles without Unity.

Loadouts

A loadout is an authored ship preset, a variant in the MechWarrior sense. Players do not see loadouts in the MVP. They are meant for spawners to build ships from; no game spawner calls Loadouts.Materialize yet.

• Content. A loadout stores item designs only: the hull design, and for each hull cell a rotation and an EquippableItemData design. It names no manufacturer and no product, so it works in any galaxy.
• Home. Loadouts live in the catalog. They are authored in CultCache Studio, or captured in play with the editor-only console command capturepreset "<name>" [replace], and they are only read at runtime.
• Capture. The process cache opens the catalog read-only in every build. Loadouts.Commit opens its own short-lived cache over Aetheria.cc, writable, commits the one preset and disposes it, so no catalog instance play holds can reach the file. The running game sees the preset after the catalog reloads.
  • A preset is keyed by its name. It replaces an existing preset only when replace is given, and a preset of the same name under another key (one authored in Studio) refuses the capture.
  • A missing Aetheria.cc refuses the capture; it never creates the catalog.
  • The commit is conditional on that key, so it writes only this one record onto the file as it is on disk.
  • The console refuses a command containing anything but letters, digits, spaces and hyphens, and quotes a multi-word name.
  • A CultCache Studio session opened before the capture overwrites captured presets when it saves, since a single-file save is last-writer-wins. Reopen the Studio after capturing.
• Materialize. Loadouts.Materialize is the only way to build a ship from a loadout, and it charges nothing.
  • Each design is built by the first available product for that design, in record-key order, under the availability predicate. The game passes LoadoutGenerator.IsAvailable.
  • It is all-or-nothing. On any failure it lists every failure and returns no ship, so a spawner can pick another preset.
• Weapon groups. Weapon groups are indices into the slots, and every index must name a slot whose design is a weapon. A loadout may have at most WeaponGroupCount groups; more is a failure. The ship always gets exactly WeaponGroupCount groups, and missing groups are added empty.
• Future direction. Variants will also differ by hardpoint configuration: one hull with alternative hardpoint layouts. This is not built yet. Nothing consumes presets yet either; ship spawning still uses LoadoutGenerator.

Target state: CultLib

• Store routing replaces replication. Each document type has exactly one home store, chosen by the record's runtime type (most specific assignable route wins). A cache with one store and no routes behaves as today. Overlapping routes, writes of an unrouted type, a record loaded from a store that is not its home, and attaching a store after hydration are errors. Multi-store replication is deleted: no consumer uses it, and transactions already refuse more than one store.
• Loading never writes. Store dirtiness derives only from mutations.
• Read-only stores. Writes routed to a read-only store throw.
• Transactions require every mutation to route to one store, replacing the rule that a transacting cache may attach only one store.
• Runtime type decides schema. The generic AddAsync<T>/UpsertAsync<T> type parameter stops choosing the schema.
• Typed lookups honor inheritance. Watch<T>, GetByName<T>, GetGlobal<T>, GetByIndex<T> match assignable types, as GetAll<T> and Get<T> already do.
• Consumers can serialize their value types (Unity.Mathematics, and whatever replaces System.Type fields) without breaking wire parity.
• CultCache Studio absorbs Database Tools: dictionaries, polymorphic [Union] fields, Unity.Mathematics types, a record picker for CultRecordRef<T>, and a custom drawer extension point.

Evidence

Runtime probe, 2026-09-12, CultLib main at c2a9a6e, generator and reflection builds, write then flush then reopen:

Case	Result
Nested [Union] field inside a document	Pass
Document inheriting [Key] fields from an unattributed abstract base	Pass
GetAll<AbstractBase>(), Get<AbstractBase>(key)	Pass
UpsertAsync<Gear>(new Weapon())	Fail: stored and reloaded as Gear, Weapon fields lost silently

Code-read, not probed: exact-type Watch/GetByName/GetGlobal/GetByIndex; no consumer formatter resolver registration (fixed static options); the generator never emits a codec for hierarchies and silently falls back; CultCache Studio lacks dictionaries, unions, math types, and a ref picker.

MessagePack 3's analyzer (MsgPack005) rejects [MessagePackObject] on an abstract type without [Union]; Aetheria's abstract ItemData, CraftedItemData, and ItemInstance must change.

Invariants

• Wire parity across runtimes; C# remains the reference.
• CultNet and CultMesh behavior is preserved or deliberately changed with every runtime updated.
• Loading a store never writes it.
• Every document type has one home store; its runtime type decides schema and route.
• ServerShared compiles headless with no UnityEngine reference.
• No code reads a legacy format.
• The migration does not bundle CultMesh hosting, Eve UI, daemons, or a state service layer.

Out of scope

CultMesh and Eve adoption in Aetheria, R3 for gameplay (UniRx stays), removing Newtonsoft attributes from the 82 files that carry them, and a state service layer.

Open questions for the Imagination pass

1. Is routing a C# cache behavior only, or a semantic every runtime's cache must match? What do the Rust, Python, and TypeScript caches do with multiple stores today?
2. How do Unity.Mathematics values encode so other runtimes can read them? Does CultMath already define portable shapes?
3. What replaces System.Type fields (StatModifierData.RequireBehavior), which have no portable encoding?
4. Do CultNet or CultMesh depend on multi-store replication, on the generic UpsertAsync<T> declared-type behavior, or on exact-type watches?
5. Can existing .cc stores in other projects hold records written under a declared parent schema, and what does fixing UpsertAsync<T> do to them?
6. Which consumers pin which CultLib revision, and what is the release and upgrade order?
7. Where exactly do Aetheria's world types fall on the document/value line, and where are the save points?
8. How do catalog identity comparisons (DatabaseEntry.Equals on ID, Dictionary<Faction,…>, Hull.Data.LinkID == data.ID) survive without DatabaseEntry.ID?

Process

A mini Epiphany loop. Imagination (a Fable agent) maps the cut into docs/cultcache-migration-cut.md: authority maps, sequenced independently executable cuts, deletion lines, negative checks, parity verification, and build budgets. Hands (Opus agents) execute the cuts. Soul (a Fable agent) verifies each against the map and the invariants above.