GameCult/Thing
Watch
9
0
Fork
You've already forked Thing
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Thing/docs/eve-migration-roadmap.md
Meta Vens 4f25a7b847 Record Sai transport graduation
2026-07-10 11:31:59 +01:00

8 KiB
Raw Blame History

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.
  • 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.
  • EveFlutter owns the generic Flutter clients and platform lifecycle.
  • Sai and Norn publish independent sidecar plugins. Sai serves retained Ink sessions through CultNet RUDP operation envelopes; Norn remains on the debug transport until the shared Rust operation host is complete. A Sai surface may request nested Norn or TeX capabilities when those plugins are available.
  • EvePlugins owns the TeX sidecar and KaTeX-backed semantic witness.
  • 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.

Remaining Work

Runtime Graduation

  • Extract EveTui when its process lifecycle and release surface are stable.
  • Move Android Kotlin and iOS UIKit lowerers into runtime owner repos or retire them when Flutter is the intended native owner.
  • Tag and publish EveUnity UPM packages; prove installation from a released package rather than sibling source paths.
  • Tag EveFlutter releases and remove remaining incubation claims.

Generic Game Lowering

  • Route browser and remaining runtimes through Odin's aggregated provider discovery rather than local catalogs or sibling paths; Unity's direct CultMesh Verse discovery is the working reference.
  • Prove cold-start Unity play from published packages plus daemon advertisements, with no Aetheria checkout available to the client.
  • 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.
  • Replace Norn's development stdio-ndjson transport with the shared CultNet operation service while preserving the same plugin ABI operations. The TypeScript host is complete and proves Sai and TeX; the Rust host must follow CultNet Rust's in-progress peer reset work instead of growing a Norn proxy.
  • Graduate remaining graph fixture ownership fully to Norn once no Eve fixture is its semantic owner. Sai already owns VN/Ink execution and its live witness.
  • Keep nested plugin availability explicit and non-transitive: Sai does not own Norn or TeX.

Conformance

  • Move remaining fixture metadata that describes product/plugin semantics to its owner pack; Eve keeps only minimal contract fixtures.
  • Run EveConformance CI against released runtime/plugin artifacts, not only sibling development checkouts.
  • Publish immutable conformance exports and capability matrices per release.
  • 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.