Aetheria/docs/cultcache-migration-postmortem.md

CultCache Migration Postmortem

Written 2026-09-15. It covers Aetheria and CultLib from the decision to migrate (2026-09-12 18:03Z) to Aetheria 58b27690 and CultLib a0813c6 (2026-09-14 23:33 local).

Related documents:

• Means: cultcache-migration-cut.md
• Ends: cultcache-migration-target.md
• Evidence behind this document: the main session transcript 2a6aec4d-7cba-481c-8586-be54662389a5.jsonl and 114 subagent records.
• The process this migration produced is formalized as the Claude Code skill ~/.claude/skills/eureka (Eureka, the Claude Code counterpart of Epiphany).

Summary

Aetheria's in-tree CultCache, the operator's original 437-line cache, has been replaced by CultLib's modern CultCache. Along the way it gained CultMath in place of Unity.Mathematics. Every piece of game state now lives in typed .cc stores with one home store per type:

• Catalog (GameData/Aetheria.cc, read-only at runtime): authored data.
• Run: the current playthrough.
• Player: settings and bindings.

Four private file formats are gone, along with the vendored MessagePack, the vendored JsonKnownTypes, and the IMGUI Database Tools. CultCache Studio edits the catalog.

Scale:

• Aetheria: +5,652 / −36,920 lines, net −31,268.
• CultLib: about +15.7k / −13.35k attributable to the migration, most of the growth being CultMath's generated HLSL surface and the new tests.
• 114 subagents ran: 50 Hands, 32 Soul, 3 Imagination, 23 Eyes/Explore, 6 Mind Steward.

Still outstanding with the operator:

• the play smoke.

The Studio click-through passed on 2026-09-17. It also found that the cutover had dropped the Database Tools' record grouping and drag-and-drop without recording them, because the feature inventory counted attributes only.

CultLib missed its own size target. The Caching core ended at 4,368 lines against a target of about 3,150, and CultCache.cs at 2,265 against about 1,000. The ledger was never reconciled.

Scope and invariants

The target was a cache-only migration.

• An earlier attempt, rolled back by 7006a6b0, had failed because it bundled CultCache, CultMesh, Eve and daemons into one change.
• AetheriaEve was ruled out as a consumer early ("preserved for taxidermy").
• CultMath was the only scope added mid-migration, by operator ruling ("it's the best workout we can give it").

Invariants carried to the end, each pinned by tests (listed in the Eyes fact sheet):

• Wire parity across runtimes, with C# as the reference.
• One home store per type, in C#, TS, Rust and Python.
• Loading never writes.
• The cache never invents globals; lifecycle owns them.
• Runtime type decides schema.
• Atomic single-store commit plus compare-exchange (proven in-process only).
• No observer runs under the cache gate; order is carried by a per-cache Sequence.
• Catalog read-only at runtime.
• ServerShared builds headless with no UnityEngine.

Timeline

Cut	Where	When (local)	Soul passes	Notable
0 target + map	Aetheria 68fbce4a..82c1e72e, second pass c3377f11..040e50b2	09-12 23:12 to 09-13 15:52	none (Imagination)	Fable ran out mid second pass
1 contract + red tests	CultLib 37f73c4..0db1fe5	09-13 16:01	1	SoA parked at parked/cultcache-soa
2 subtraction	d904960..14d7c64	09-13 16:21 to 17:17	1	−2,533 lines; 5 kept durability invariants had lost their tests
3 routing, atomic commit, Sequence	a3cc394..825b4f7	09-13 17:57 to 21:02	6	deadlocks, a lost write, a ticket system built and then deleted
4 serialization, generator deleted	6fcc2a7..5bd4e4e	09-13 21:09 to 09-14 00:21	3	keyed get-only data loss
5 TS/Rust/Python	8dd5a45..47c7111	09-14 00:37 to 12:43	4	"BROKEN against its own contract" on pass 1
6 Studio on an engine-free model	8be174b..741d212	09-14 13:02 to 14:55	4	unloadable-store key, IMGUI split authority
6b CultMath HLSL parity	d514efe..d4c43ed, merged 1b95dd6	09-14 13:29 to 14:57	4	step NaN taken from docs rather than dxc
7 release	546c919, ae194d5	09-14 15:16	0	the tag push silently skipped publish
CultMath 0.2.1 to 0.2.3	f060536, 111b918, 0f2c1f0	09-14 16:16 to 18:19	via 8a	gaps filled in the owner, not the consumer
8a CultMath swap	Aetheria 4f4beb0f..2b38d2dc	09-14 17:38 to 18:29	2	SectorMap pivot, degenerate zone seeds
8b data model	b4c06b50..9bdf6ef2	09-14 18:42 to 19:17	1	Unity attached no run store
CultLib 1.0.58 / 1.0.59	b85a828, a0813c6	09-14 21:01 to 21:35	1 + 1	nil map key broke Python
9 importer	70fbaca1	09-14 21:11 to 21:23	1	dangling refs traced to 2021 deletions
10 runtime cutover + presets	4a545469..58b27690	09-14 21:43 to 23:33	3	untested operator rulings; catalog writable in editor

The whole migration took about 48 hours of wall clock, including one night.

Structural delta

Aetheria.

• The ledger estimated −33,000; actual is −36,920 / +5,652 (net −34,388 excluding docs).
• Cut 8b alone removed 35,989 lines, of which 31,293 were vendored MessagePack and Unsafe.dll.
• Added:
  • three UPM git pins;
  • a CultLib pin guard;
  • Aetheria.Shared.Tests (29 tests);
  • AetheriaStores, RunSave, Loadout, StableHash;
  • GameData/Aetheria.cc under LFS.
• 20 document schemas replace one root union.

CultLib.

• Removed:
  • the MessagePack generator and the empty Analyzers project;
  • SoA (parked, not deleted);
  • the managed document;
  • ambient transactions;
  • initializeGlobals;
  • the TS/Rust/Python mirrors;
  • the v2/v3 directory formats;
  • typed serialize helpers;
  • the Studio's by-name reflection bridge;
  • the composite constructor heuristic;
  • the soft flush flag in core.
• Added:
  • Commit(Action<CultCacheBatch>) with Expect/TryCommit;
  • a per-cache Sequence;
  • CultInspectorModel;
  • CultMath's HLSL surface, Unity bridge, pinned dxc, and PCG hashes;
  • Contracts/cultcache-store-composition.md.

The core size miss has visible causes. Soul-driven gate and publication rules, compare-exchange, and the registry absorbing the generator's rules all added lines, and the inspection model moved into core. None of these was weighed against the target. The ledger stopped being updated after Cut 4.

What Soul caught

32 Soul passes ran; 29 found at least one real defect that Hands' tests and report had passed. The tally is roughly 75 defects. They fall into a few families.

Concurrency. Five deadlocks, stalls or hangs:

• Cut 3's pull/upsert deadlock on directory stores, which hung 3 of 3 runs.
• A ticket-ordered delivery that deadlocked through CultNetDatabaseSubscriptionServer._lifecycleGate and could stall a cache forever.
• TS's per-cache queue deadlocking when a store awaited its own cache.
• TS's AsyncLocalStorage re-entry guard, which both over-refused and missed escaping waits.

Each of these had passing tests. Cut 3's race tests were red only on Windows, by accident.

Lost writes and data loss.

• A re-pull erased a staged write the contract said was safe.
• A shared unpublished-changes list let one throwing observer discard other threads' committed changes.
• Keyed get-only members were silently skipped.
• Studio Save deleted presets captured during play.

Wire parity.

• 1.0.58 wrote an unset CultRecordRef dictionary key as nil, which Python's msgpack rejects under strict_map_key. It was released, then corrected 74 minutes later in 1.0.59.
• A Python global stored under a legacy key made the cache unloadable.

Semantics taken from the wrong authority.

• CultMath's step NaN rule came from documentation. dxc compiles it the other way.
• The matrix row indexer silently wrote to defensive copies.
• The HLSL mirror "compiled as C#" claim was false at first.
• The mirror test later proved only compilation, not values.

Lifecycle and ownership.

• 8b. Unity attached no run store, so every run write threw. Hands had described those paths as "upserting orphans". Separately, PlayerSettings.SavedRun was a second owner of the run root.
• 10. The catalog was read-only in the editor only by convention. It had been opened writable for preset capture.
• Split authority recurred at small scale. Affordability stayed in the menu after the charge moved into Materialize. The IMGUI Studio kept key, element and narrowing decisions after the model was supposed to own them.

Untested operator rulings.

• Cut 10. Removing the availability rule, the price rule, or all-or-nothing on a failed fit left all 15 tests green. Hands' "each new test fails under its mutation" covered only the tests Hands chose to write.
• Cut 6. 3 of 7 inspection-model tests survived removal of their own rules.
• Cut 2. Five durability invariants that were kept had lost their tests along with the stage probes.

Behaviour the captures could not see (8a).

• sign returns int, so SectorMap's sign(x)/2+.5f became integer division.
• CultMath's shader-style hash gave 1,625 distinct zone seeds in 10,000 positions.

What these share. The defect was invisible at the layer where the author checked: unit tests in one runtime, captures that did not exercise the code path, or a rule read from a document instead of the compiler. Soul found them by checking at the layer where each would actually fail: another runtime's decoder, dxc's lowered IR, Unity's decompiled EditorGUI, an independent decode of the legacy file, or a scratch probe over every document type.

The pass that did not run. Cut 7, the release, got no Soul pass. Its problems surfaced late:

• stale committed DLLs;
• a commit SHA baked into release byte checks;
• a native DLL rebuilt nondeterministically;
• a tag push that silently skipped publishing.

Hands or later Soul passes found each of these, but after tags were already pushed.

Operator corrections

35 rulings or corrections are recorded, with quotes, in the Eyes fact sheet. The ones that matter here are those where the agents' model was wrong. For each, the question is what context was missing.

• Defunct neighbour repos treated as parity runtimes. No doctrine said where canonical runtimes live. Fixed at the source: F:\Projects\CLAUDE.md now names CultLib\packages\ as the only home.

• Imagination stated cause and effect it never traced ("the effects you listed don't follow from the causes", 09-12). The map made mechanism claims from names. From then on, the brief standard required probes for every mechanism claim.

• Mirrors and non-decisions. Replication had no consumers, and "3-5 are not decisions". The consumer audit came after the questions instead of before them.

• "Soul pass on the cut map" was a faculty confusion. It is now in doctrine: a pass over a plan is Imagination.

• initializeGlobals. The cache invented globals because Aetheria had a lifecycle problem. The operator named the real owner: lifecycle.

• Style bar. "Does the current code look anything like that". Four months of drift had nobody holding the original design up for comparison. The original 437-line cache became the explicit bar.

• Atomic commit and compare-exchange were slated for deletion as unused in C#. The operator knew they had been needed across Ghostlight and Epiphany. A consumer count limited to C# undercounted a capability the operator uses across projects.

• Generator ("do we even need a generator anymore?"). Once MessagePack became canonical, the generator only duplicated the registry's rules. The map had kept it because it existed.

• Tickets, then Sequence ("an itch regarding authority here"). Order was first carried by scheduling, as tickets that serialized delivery. The operator preferred order as data. A whole ticket subsystem was built, found deadlocking by Soul, and deleted.

• CultMath "drop-in" and the Unity license. Both claims were wrong until checked, by audit and by the operator. HLSL, not Unity.Mathematics, was the real parity target, and only the operator knew that.

• Composite heuristic ("what a silly and fragile idea"). Hands invented a constructor-matching guess to fill a drawer gap. It had no owner and no consumer.

• Loadouts, three definitions in one evening.

  1. The spec made loadouts player-store builds with a product per slot.
  2. "Blueprint means design": no manufacturer.
  3. "Think variants in Mechwarrior": authored catalog presets, not player-facing.

  Each redefinition reworked shipped code. The missing context was product meaning. Nobody asked what a loadout is for before specifying its store, its UI and its price. Imagination inferred the purpose from a broken legacy menu.

Incidents

• Probe fork bomb, 2026-09-13. An Imagination probe (cc-cas-probe) relaunched Environment.ProcessPath with the dll as an argument, so every child re-ran the parent. Starfire needed two hard reboots and survived a third process storm only through a cancelled shutdown. It cost about two hours and woke the operator's household. PCIe ASPM was blamed first. The probe (P7, the two-process race) never produced a result, so cross-runtime lock exclusion is still unproven. The operator ruled out process-spawn policing. The kept lesson is narrow: read how a child chooses its role before running launch code.
• Fable exhausted before Cut 1 (HTTP 429 at 13:51Z on 09-13). The plan had Fable on Imagination and Soul. Only 1 of 114 agents ran on Fable. Opus carried every other pass, including all 32 Souls, and the Soul hit rate held.
• Permission classifier. It blocked a Hands edit, then a Hands git add -A && git commit -F - <<EOF during Cut 2. The coordinator made the commit (88e1c8e). Briefs changed to message files, with "if blocked, stop and report".
• BOM commit subjects. PowerShell 5.1 Set-Content -Encoding utf8 wrote BOMs into message files. Two pushed CultLib commits (5aad137, e0a054a) start with one; they were left, since fixing them needs a force-push. The rule is to write message files with the Write tool.
• Parallel Hands shared commit-message filenames. This was a near miss; no commit was actually swapped.
• git add -A swept PlayerSettings.msgpack into 5c5c3d5e. It was untracked a commit later, but it stays in history. About 65 earlier LFS versions already existed, so history was left alone.
• More than three tags in one push. GitHub skipped the tag workflows, and no publish ran. cultcache-py 0.3.0 was re-pushed alone and reached PyPI. npm publication is parked by choice (CultLib QUIC map, Q5 C, 2026-09-16); no NPM_TOKEN exists and none is planned for now.
• Stale incremental DLL. a9a2ba6 shipped a CultMath DLL from an incremental build that did not recompile. The release script now builds non-incrementally without Source Link. The native QUIC DLL got /Brepro.
• An interrupted operator question. A tool-based question was rejected after about an hour while the operator moved devices, and was re-presented as text.

What worked

• A separate falsifier. A pass that finds real defects 29 times in 32 is not ceremony. It held on Opus.
• Rulings with options and a recommendation. The operator could answer "AAA" from a phone, and every answer landed in the map with its wording.
• Gaps filled in the owner. CultMath gained conversions, integer clamp, frac(double), a dxc-matching normalize and PCG hashes. Aetheria grew no helpers, and AetheriaMath.cs was deleted.
• Deleting old authorities before adding new ones. Aetheria's four private formats, the vendored libraries, the importer and SavedRun are gone, not demoted.
• Captures across cuts. census, factions and hardpoint-fit stayed byte-identical from 8a through 10. That made the importer checkable, and made behaviour changes elsewhere visible by their absence.
• Mind Steward at boundaries. It caught stale claims, including the unmerged PackageCache coupling, player-store loadouts and "spawners materialize". It also moved process lessons into the skill.

What to change in the pipeline

These are applied to the Eureka skill and recorded in its changelog.

1. Soul before any release or tag. The release cut got no Soul pass, and 1.0.58 shipped a wire-parity defect found an hour later.
2. Ask what a domain concept is for before specifying it. Loadouts were rebuilt twice because product intent was inferred from a broken menu.
3. Reconcile the subtraction ledger at every landing, and at close. The CultLib size miss went unexamined.
4. Every operator ruling gets its own failing mutation, listed in the Hands brief and checked by Soul. Cuts 2, 6 and 10 all shipped rulings or invariants with no pinning test.
5. Count a capability's consumers across every project the operator works in, not only one runtime's repos. Atomic commit and compare-exchange were nearly cut.
6. Prefer order carried as data over order carried by scheduling when designing concurrency in a map. The ticket system was the costliest dead end.
7. Safety check on process-launching probes: read how a child chooses its role before launching it.

Open follow-ups

• Operator: play smoke.
• Studio grouping and drag-and-drop: restore as member attributes; owned by CultLib\docs\studio-grouping-cut.md.
• CultLib:
  • Studio detects on-disk changes before Save.
  • The release byte check is enforced by script.
  • Collapse the dead empty-key check in CultRecordRefFormatter.
  • Unset-ref contract wording.
  • Remove soft from CultMesh/CultNetLocal and their callers.
  • CultNet/CultMesh sequence gaps.
  • By-name reflection in Networking and Mesh.
  • Prove cross-runtime lock exclusion (Rust fs2 against C# FileShare.None) and the P7 two-process race.
  • Reconcile the core size ledger.
• Consumers to re-pin: Delvehold (generator ProjectReferences), EveUnity (Deserialize<T>), Epiphany and CodexConnector (Rust Result, push_all), VoidBot (TS promises), Heimdall.
• Aetheria:
  • No spawner uses presets yet (candidates: ZoneGenerator.cs:309, ActionGameManager.StartGame).
  • Hardpoint-configuration variants.
  • New Game clears the old run before generation succeeds.
  • LookRotation NaN is unpinned.
• Release: npm cultcache-ts 0.14.0 is tagged and unpublished by choice; registry publication is a later pass. Unity 1.0.47 to 1.0.56 were never tagged.