236 lines
13 KiB
Markdown
236 lines
13 KiB
Markdown
# 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
|
|
|
|
```powershell
|
|
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.
|