Thing/docs/eve-migration-roadmap.md

Eve Migration Roadmap

Objective

Eve is the contract kernel for a runtime-independent meta-game engine. A game daemon publishes typed surfaces, commands, state bindings, assets, and plugin requirements. Generic runtime clients lower those documents without knowing the game. Semantic plugins run as sidecar daemons behind the Eve plugin ABI and remain independent of rendering engines.

The proving scenario is Aetheria: its daemon publishes a 3D ARPG world surface that a generic EveUnity client lowers into a playable game without importing Aetheria code or assets as runtime authority.

Authority Map

Owner	Authority
Eve	Surface, command, provider, plugin, runtime, and receipt contracts; CultUI DSL; browser reference lowerer; minimal core fixtures
EveConformance	Fixture matrix, parity runner, capability ledger, witness attachment, portable exports, and cross-repo CI orchestration
EvePlugins / plugin owner repos	Runtime-independent semantic sidecars, domain fixtures, and plugin witnesses
EveUnity, EveElectron, EveFlutter, future runtime repos	Native projection, plugin transport, platform lifecycle, captures, and runtime tests
Aetheria and other providers	Live state, authored surfaces, assets, command handling, receipts, and product scenarios

Boundary rule: Eve owns contracts. Plugins own semantics. Runtimes own native projection. Providers own live truth. EveConformance owns proof.

No runtime may import provider or plugin internals. Provider/plugin advertisements and typed command/receipt documents are the boundary.

Live Data Flow

1. A provider daemon advertises surfaces, schemas, commands, assets, and plugin requirements through CultMesh/CultNet documents.
2. A generic runtime selects a surface and resolves required plugin advertisements.
3. Plugin operations execute through the runtime-independent sidecar ABI.
4. The runtime lowers the resulting Eve surface into native presentation and emits typed command invocations.
5. The provider remains the sole writer of game state and returns typed receipts/state updates.
6. EveConformance joins owner manifests and witnesses into a portable report; it never becomes provider or runtime truth.

Completed Migration

• EveUnity owns the Unity scene and UI Toolkit packages. Aetheria consumes those packages directly.
• The generic EveUnity playable-world client lowers the separately running Aetheria daemon's 3D ARPG world, resolves provider-owned assets, and exercises movement, targeting, and fire command receipts.
• EveUnity's clean TestProject owns generic scene and UI Toolkit package verification; ordinary runtime tests no longer open or mutate Aetheria.
• Eve owns the renderer-neutral surface package. EveUnity publishes the Unity UI Toolkit and scene lowerers from one immutable repository commit; its isolated consumer resolves those packages plus CultLib without borrowing a provider's source tree. Aetheria pins the same owner commits.
• The same isolated-package consumer cold-starts from Aetheria's CultMesh rendezvous endpoint with no configured provider or surface ID, discovers the daemon's interactive-world, loads provider-owned assets, and reconciles movement, targeting, and action receipts without importing Aetheria code.
• Aetheria pins the same EveUnity commit; no Aetheria Unity component constructs the generic CultMesh client transport used by that witness.
• EveUnity can start from one CultMesh rendezvous endpoint, discover a Verse, select an advertised interactive-world surface, and connect without configured Aetheria provider or surface identifiers. The Aetheria daemon publishes its Verse catalog on the same client endpoint.
• CultLib emits a verified NuGet dependency closure for GameCult.Mesh and a clean package-reference consumer, while Unity consumes the corresponding org.gamecult.cultlib UPM assembly closure.
• CultLib publishes transport-neutral cultnet.operation_request.v0 and cultnet.operation_response.v0 envelopes in TypeScript, C#, and Rust. These carry Eve plugin ABI documents without moving plugin semantics into CultLib.
• EveElectron owns its shell, security lifecycle, captures, and runtime witness.
• EveElectron owns its Electron test dependency and consumes Aetheria capture inputs from Aetheria's provider pack; it no longer borrows Aetheria's node_modules or Eve-local copies of product fixtures.
• EveElectron owns EveCultMeshProviderClient, the generic live RUDP provider transport. It starts from an Odin-resolved peer and advertisement record, follows provider-advertised surface/command/receipt/document references, and does not compile provider IDs, schemas, or record keys into the runtime.
• Aetheria's Electron client now delegates live provider advertisement, surface, embedded-document, command invocation, and receipt reads to that EveElectron transport. Its cold daemon witness proves the shared CultNet connection contract, portable Eve MessagePack documents, provider acceptance, and deterministic receipt records. The superseded Aetheria surface/provider readers, command serializer, and generated Eve IPC handler authority have been deleted. AetheriaCultMeshClient no longer exposes any Eve-facing method.
• EveElectron owns the standalone preload entry and generic browser renderer bootstrap. Aetheria consumes those runtime bodies directly; its generated renderer API contract, product preload, preload copy script, and product IPC registration are deleted.
• EveElectron owns the live main-process provider host: secure window creation, provider client construction, Eve IPC and receipt handling, provider readiness, renderer loading, and cleanup. Aetheria delegates that lifecycle and retains only daemon development launch, provider target configuration, its live smoke scenario, and provider-owned asset records.
• EveElectron owns generic CultMesh asset reads and the eve-asset protocol. The Aetheria renderer and main process contain no product asset transport; the cold-daemon witness decodes a provider-owned world image through the generic runtime path.
• EveFlutter owns the generic Flutter clients and platform lifecycle.
• Sai and Norn publish independent sidecar plugins. Sai serves retained Ink sessions and Norn serves graph projection and measurement through CultNet RUDP operation envelopes. A Sai surface may request nested Norn or TeX capabilities when those plugins are available.
• Norn owns the nested graph document, layout semantics, runtime advertisement, ABI fixture, and conformance evidence. Eve's Sai contract fixture carries only an embed.norn capability request and Norn-owned CultMesh document reference.
• EvePlugins owns the TeX sidecar and KaTeX-backed semantic witness.
• EvePlugins owns the independent fields.surface sidecar, generic gamecult.fields.* document model, fixtures, tests, and CultNet witness. Aetheria remains owner of sampled field truth; runtimes remain owners of native field projection.
• Aetheria publishes objects, gravity, and render splats as gamecult.fields.* documents and advertises fields.surface on graphical surfaces that use them. Hermodr carries decoded MessagePack values without interpreting field schemas or tuples; each runtime's Fields adapter owns conversion and projection.
• The browser fields adapter owns field component matching, canvas lifecycle, provider-document polling, tuple conversion, Canvas/WebGL projection, GPU resources, asset overlays, and capability-gap reporting. The general CultUI lowerer dispatches plugin component kinds without field-specific branches.
• EvePlugins publishes runtime-neutral C# fields contracts as UPM and .NET packages. EveUnity scene owns the second native adapter: structured splat buffers, RenderTexture rasterization, layer texture allocation, and the generic fields shader. Aetheria implements the plugin interfaces and retains only a MonoScript-GUID compatibility shell; its buffer, shader, layer filtering, blend selection, and texture-allocation authority are deleted. Aetheria retains only the table mapping canonical layers onto product material properties and shader globals.
• The released Unity adapter's provider-independent EditMode witness renders a synthetic gamecult.fields.splats.v1 document through the GPU path, asserts nonblank pixels, and writes artifacts/fields-surface/latest/unity-fields.png. With browser and Unity native proofs plus the sidecar witness, fields.surface is graduated in EvePlugins.
• The TeX owner sidecar serves its Eve ABI over CultNet RUDP operation envelopes; its stdio protocol is retained only as a local debug adapter.
• Aetheria owns its provider advertisement, world surface, scenario, asset manifest, and conformance pack.
• EveConformance owns the parity manifest, runner, fixture exporter, witness attachment, export consumer, and report artifacts.
• Eve retains the browser reference as the behavior oracle and a minimal generic interactive-world fixture.
• The browser reference starts through Odin-owned Hermodr, preserves advertised provider and surface identity, selects interactive-world by capability, and resolves assets through provider-advertised CDN routes. Its live startup path contains no Aetheria identifiers; local catalogs remain offline oracle data.
• EveConformance materializes all provider, plugin, runtime, and kernel inputs from public Git URLs at immutable commits. Cold conformance runs reject checkout/lock mismatches and export the evidence lock coordinates plus digest, so sibling development layout is no longer conformance authority.
• EveConformance CI runs that locked public workspace on every push and uploads a commit-keyed evidence bundle. Version tags attach the same lock, reports, capability matrix, packs, captures, and typed witnesses to a GitHub release.
• EveTui owns the terminal lowerer, command-intent projection, package and test lifecycle, and durable Aetheria/generic-world grid captures. Its 0.1.1 package is built from the owner repo; Eve no longer contains a TUI runtime.
• EveFlutter owns its platform clients, lifecycle, responsive Windows goldens, native capture runners, and Linux CI captures. The tagged 1.0.2 owner build analyzes, tests, regenerates platform captures, and publishes them from CI.

Remaining Work

Runtime Graduation

• Move Android Kotlin and iOS UIKit lowerers into runtime owner repos or retire them when Flutter is the intended native owner.

Generic Game Lowering

• Route remaining runtimes through Odin's aggregated provider discovery rather than local catalogs or sibling paths; browser/Hermodr and Unity direct Verse discovery are the working references.
• Expand world lowering only through generic surface contracts: entities, transforms, animation state, collision/navigation intent, cameras, effects, interaction prompts, and command boundaries.
• Keep simulation, AI, inventory, combat resolution, and authored world truth in Aetheria.

Plugin Architecture

• Publish the verified CultLib NuGet and Unity package artifacts from tagged releases and consume released versions in runtime CI.
• Publish the shared TypeScript and Rust CultNet operation hosts from tagged CultLib releases. Sai, Norn, and TeX prove the same operation envelope across both language implementations; stdio remains a local diagnostic adapter.
• Keep nested plugin availability explicit and non-transitive: Sai does not own Norn or TeX.
• Move any remaining provider-specific field source composition only when it can consume the portable contracts without weakening provider ownership. Keep projection native to each runtime; do not move Canvas/WebGL or Unity shader implementation into plugin semantics.

Conformance

• Move remaining fixture metadata that describes product/plugin semantics to its owner pack; Eve keeps only minimal contract fixtures.
• Remove obsolete split-handoff schemas and checks after every named owner repo has a released consumer path.

Graduation Criteria

• A runtime splits when it has its own build/deploy lifecycle or platform SDK pressure.
• A plugin splits when it owns domain semantics, fixtures, and conformance cases.
• A product fixture splits when it carries product state, assets, flows, or receipts.
• Conformance remains independent when runtimes/plugins consume its export without depending on Eve's checkout layout.

Acceptance

The migration is complete when:

1. A clean generic EveUnity client installed from published packages discovers Aetheria through the Verse and plays its 3D world without Aetheria code.
2. Sai, Norn, and TeX execute as independent runtime-agnostic sidecars and can be composed through advertisements.
3. Browser, Unity, Electron, Flutter, and TUI/native owners consume the same provider contracts and report honest capability gaps.
4. Eve answers "what is the contract?" without carrying product state, plugin semantics, platform build bodies, or conformance orchestration.
5. EveConformance can verify released providers, plugins, and runtimes from public artifacts and typed witnesses.

Verification

node --test web/eve-dsl.test.mjs
npm --prefix packages/eve-browser-lowering test
powershell -ExecutionPolicy Bypass -File .\scripts\run-parity-harness.ps1

run-parity-harness.ps1 is an Eve compatibility entry point. The matrix and runner it invokes are owned by the sibling EveConformance repository.