405 lines
19 KiB
Markdown
405 lines
19 KiB
Markdown
# Eve Migration Roadmap
|
|
|
|
Date: 2026-07-08
|
|
|
|
The great Eve migration is the move from a useful pile of renderer proofs,
|
|
fixtures, provider demos, and platform experiments into a kernel-shaped system:
|
|
Eve core owns contracts, plugins own semantics, runtime repos own native
|
|
projection, and provider repos own live truth.
|
|
|
|
This is not a repo cleanup campaign. It is an authority migration. The split is
|
|
complete only when the old in-repo convenience paths can no longer decide
|
|
provider truth, plugin semantics, or runtime behavior by accident.
|
|
|
|
## Objective
|
|
|
|
Make Eve the stable interactive language for CultMesh surfaces without turning
|
|
`E:\Projects\Eve` into a permanent warehouse.
|
|
|
|
The target shape:
|
|
|
|
- Eve core: surface contracts, CultUI DSL, command/binding descriptors,
|
|
provider/plugin advertisement specs, browser reference, and conformance
|
|
harness incubation.
|
|
- EvePlugins: first-party reusable semantic plugins while young.
|
|
- Owner repos: Sai owns VN/Ink, Norn owns graph semantics, providers such as
|
|
Aetheria own live state and authored product surfaces.
|
|
- Runtime repos: EveUnity, EveFlutter, EveAndroid, EveIOS, EveGodot, EveElectron,
|
|
Fensalir/Direct2D, and future bodies own projection, build glue, plugin
|
|
projection adapters, capture, and runtime tests.
|
|
- EveConformance: fixture corpus, parity runner, capability matrix,
|
|
screenshot/report artifacts, plugin packs, and CI once the harness is stable
|
|
enough to leave Eve core.
|
|
|
|
## Current Authority Map
|
|
|
|
Owner:
|
|
|
|
- Eve owns `gamecult.eve.surface.v1`, `gamecult.eve.command.v1`, CultUI,
|
|
provider/plugin advertisement contracts, plugin ABI shape, browser reference
|
|
behavior, and parity/conformance policy.
|
|
|
|
Inputs:
|
|
|
|
- Local fixtures under `web/fixtures`.
|
|
- Incubating plugin manifests under `plugins/incubating`.
|
|
- Runtime claims in `tools/parity/parity-manifest.json`.
|
|
- Provider advertisements such as Repixelizer's local fixture.
|
|
- Hermodr/Odin/CultMesh live provider surfaces when available.
|
|
|
|
Outputs:
|
|
|
|
- Browser reference lowering.
|
|
- Runtime capability reports.
|
|
- Plugin capability gaps.
|
|
- Parity reports under `artifacts/parity`.
|
|
- Split targets and graduation triggers in the parity manifest.
|
|
|
|
Derived state:
|
|
|
|
- Local provider lists are fixture advertisements, not discovery truth.
|
|
- Runtime capability status is diagnostic, not provider authority.
|
|
- Screenshot/golden artifacts are evidence, not portable state.
|
|
- In-repo runtime/plugin bodies are incubation, not permanent ownership.
|
|
|
|
Forbidden writers:
|
|
|
|
- Runtime lowerers must not import provider internals to recover missing
|
|
semantics.
|
|
- Plugins must not mutate provider truth or accept provider commands.
|
|
- Product demos must not become Eve core fixtures once they carry product state,
|
|
assets, receipts, or deployment assumptions.
|
|
- Compatibility HTTP routes and browser tabs must not replace provider
|
|
advertisements.
|
|
- Passing parity tests must not preserve a body that cannot name its owner,
|
|
inputs, outputs, and split trigger.
|
|
|
|
Shared paths:
|
|
|
|
- Every runtime claim flows through `tools/parity/parity-manifest.json`.
|
|
- Every fixture belongs to a conformance pack: `core`, `plugin`, `provider`, or
|
|
`runtime`.
|
|
- Every plugin claim names owner repo, split target, capabilities, required
|
|
fixtures, and graduation trigger.
|
|
- Every runtime claim names owner repo, repo role, split target, supported
|
|
features, plugin support, and graduation trigger.
|
|
|
|
Deletion line:
|
|
|
|
- Cut hardcoded provider tabs before adding new live providers.
|
|
- Cut renderer-specific product knowledge before claiming generic Eve support.
|
|
- Cut in-repo runtime/plugin bodies once their contract and release lifecycle
|
|
stop changing.
|
|
|
|
## Phase 0: Ledger And Contract Grounding
|
|
|
|
Status: underway.
|
|
|
|
Purpose: make ownership visible before moving code.
|
|
|
|
Work:
|
|
|
|
- Keep `docs/repo-strategy.md` as the repo boundary doctrine.
|
|
- Keep this roadmap as the migration sequence.
|
|
- Keep `tools/parity/parity-manifest.json` as the machine-readable ownership
|
|
ledger.
|
|
- Keep `docs/surface-contract-v1.md`,
|
|
`docs/provider-advertisement-contract.md`, and
|
|
`docs/plugin-architecture.md` as the contract source of truth.
|
|
- Keep browser reference and parity harness green after every migration cut.
|
|
|
|
Exit criteria:
|
|
|
|
- All fixtures declare a conformance pack.
|
|
- All incubating plugins declare owner, split target, capabilities, and required
|
|
fixtures.
|
|
- All runtimes declare owner, repo role, supported features, plugin claims, and
|
|
graduation trigger.
|
|
- Harness reports missing ownership metadata and plugin gaps explicitly.
|
|
|
|
Current proof:
|
|
|
|
- `node --test web\eve-dsl.test.mjs`
|
|
- `powershell -ExecutionPolicy Bypass -File .\scripts\run-parity-harness.ps1`
|
|
|
|
## Phase 1: Stabilize Core Surface Contract
|
|
|
|
Purpose: make the surface contract boring enough that runtimes and providers can
|
|
leave the repo without dragging hidden behavior with them.
|
|
|
|
Work:
|
|
|
|
- Normalize `surface.root`, `surface.styles.tokens`, `stateBindings`,
|
|
`embeddedDocuments`, command templates, and operation invocation descriptors.
|
|
- Keep compatibility fields such as `nodes`, `selectedNodeId`, raw `command`,
|
|
and string payloads as projections only.
|
|
- Add explicit authority/staleness witness UI in the browser reference for
|
|
stale, missing, predicted, denied, accepted, and reconciled values.
|
|
- Add provider advertisement fixture checks for local and live discovery paths.
|
|
First cut is in place for Repixelizer and Aetheria provider advertisements.
|
|
- Add plugin advertisement fixture checks before adding more plugin semantics.
|
|
|
|
Exit criteria:
|
|
|
|
- Browser reference can open all local fixtures through advertisement-shaped
|
|
provider entries.
|
|
- New renderer APIs construct commands from CultMesh operation descriptors, not
|
|
raw strings.
|
|
- New binding APIs carry CultMesh state binding descriptors, not renderer-local
|
|
stores.
|
|
- Parity harness fails if embedded slots, required bindings, command descriptors,
|
|
or provider advertisement fields disappear.
|
|
|
|
## Phase 2: Split Conformance Shape From Runtime Bodies
|
|
|
|
Purpose: make the evidence path portable before runtime repos leave.
|
|
|
|
Work:
|
|
|
|
- Promote `tools/parity` from a local script into a conformance pack layout:
|
|
fixture metadata, expected capability matrix, runtime adapters, plugin packs,
|
|
and report schema.
|
|
- Separate core fixtures from plugin/provider/runtime fixtures.
|
|
- Add screenshot comparison metrics for structure, token colors, bounding boxes,
|
|
text presence, and capability-gap overlays without pretending byte-identical
|
|
pixels are the goal.
|
|
- Keep generated reports under `artifacts/parity` as evidence only.
|
|
|
|
Exit criteria:
|
|
|
|
- A runtime repo can run conformance against Eve fixtures without importing Eve
|
|
source internals.
|
|
- Plugin conformance packs can be added without editing core harness logic.
|
|
- `EveConformance` has a clean split plan, or stays incubating only because the
|
|
report schema is still changing.
|
|
|
|
## Phase 3: Graduate Plugins
|
|
|
|
Purpose: move semantic ownership out of Eve core.
|
|
|
|
Work:
|
|
|
|
- Keep `plugins/incubating/sai-vn.plugin.json`,
|
|
`plugins/incubating/norn-graph.plugin.json`, and
|
|
`plugins/incubating/tex-math.plugin.json` as temporary manifests.
|
|
- Define `gamecult.eve.plugin.v1` and
|
|
`gamecult.eve.plugin_advertisement.v1` as explicit schemas. First-cut JSON
|
|
schemas live under `schemas/` and the parity harness validates incubating
|
|
plugin manifests and advertisements against them.
|
|
- Add plugin ABI fixtures for `describe`, `validate`, `project`, `apply`,
|
|
`lower`, and `measure` where relevant.
|
|
- Move `sai.vn` to Sai when VN/Ink story state, visual manifest, story commands,
|
|
and projection fixtures are stable.
|
|
- Move `norn.graph` to Norn when graph layout, interaction, fallback, and
|
|
conformance fixtures are stable.
|
|
- Move `tex.math` to EvePlugins when TeX source, macro, baseline, cached render,
|
|
and fallback fixtures are stable.
|
|
|
|
Exit criteria:
|
|
|
|
- Eve core knows plugin manifests and capability gaps, not plugin internals.
|
|
- Providers invoke plugins through the ABI object model.
|
|
- Runtimes declare plugin support through capability manifests.
|
|
- Unsupported required plugin capabilities appear as visible gaps.
|
|
|
|
## Phase 4: Graduate Runtime Bodies
|
|
|
|
Purpose: let runtime repos own native projection without losing conformance.
|
|
|
|
Work:
|
|
|
|
- EveFlutter: provider picker, command transport, plugin projection adapters,
|
|
Android/iOS/desktop build flow, native capture, and parity reports.
|
|
- EveUnity: UPM package release, plugin projection adapter behavior,
|
|
resolver-backed embedded documents, Unity test/capture lifecycle, and Aetheria
|
|
consumption.
|
|
- EveAndroid: Kotlin device edge, generic surface traversal, sensor publishing,
|
|
Android-specific CI, and explicit discovery input.
|
|
- EveIOS: UIKit renderer, sensor edge release flow, fixed-device and simulator
|
|
capture, and generic surface lowering.
|
|
- Fensalir/Direct2D: Eve-to-`AquariumUiDocument` adapter, DirectWrite/Direct2D
|
|
token lowering, embedded slot preservation, and frame capture.
|
|
- EveWeb: stays in Eve while it is the behavior oracle; splits only if it becomes
|
|
an independently deployed runtime product.
|
|
|
|
Exit criteria:
|
|
|
|
- Runtime can build, test, capture, and report conformance without sharing Eve's
|
|
dirty worktree.
|
|
- Runtime consumes surface documents, plugin manifests, and provider
|
|
advertisements through contracts.
|
|
- Runtime has no provider-specific renderer brain unless it is explicitly a
|
|
provider-owned app.
|
|
|
|
## Phase 5: Move Product Fixtures To Provider Repos
|
|
|
|
Purpose: prevent demos from becoming quiet product authority inside Eve.
|
|
|
|
Work:
|
|
|
|
- Repixelizer owns job/session/artifact/operator fixtures once they carry real
|
|
product state or receipts.
|
|
- Aetheria owns RTS/ARPG world surfaces, assets, generated level state, command
|
|
receipts, and scenario conformance.
|
|
- Huginn owns `.cc` and Persona-state inspection fixture packs when they depend
|
|
on runtime stewardship details.
|
|
- Mimir owns sensor/media/control surfaces that depend on live stream timing or
|
|
room state.
|
|
|
|
Exit criteria:
|
|
|
|
- Provider repo publishes provider advertisements and fixture/conformance packs.
|
|
- Eve core keeps only minimal generic fixtures and references provider packs by
|
|
contract.
|
|
- Product assets and receipts are not stored as Eve core truth.
|
|
|
|
## Phase 6: Cut Compatibility Paths
|
|
|
|
Purpose: make old routes unable to reassert authority.
|
|
|
|
Work:
|
|
|
|
- Remove hardcoded browser provider tabs once live/local advertisements cover
|
|
the same flows.
|
|
- Remove direct Mimir deck probing from generic Eve paths.
|
|
- Remove renderer-private style shortcuts once token lowering is complete.
|
|
- Remove raw command construction APIs from new public runtime paths.
|
|
- Remove provider-specific renderer fallbacks from generic lowerers.
|
|
|
|
Exit criteria:
|
|
|
|
- The only normal path is provider advertisement -> surface document -> runtime
|
|
lowering -> command intent -> provider receipt -> republished state.
|
|
- Compatibility routes exist only as named lowerings or debug probes.
|
|
- Parity and runtime diagnostics report the same layer of reality the user sees.
|
|
|
|
## Active Work Queue
|
|
|
|
1. Move EveUnity toward split readiness with runtime-owned UPM release and
|
|
Unity capture/test lifecycle evidence.
|
|
|
|
Recently cut:
|
|
|
|
- Sai, Norn, and TeX plugin ABI fixtures now cover `lower` and `measure` in
|
|
addition to `describe`, `validate`, `project`, and `apply`. Eve validates the
|
|
operation shape, preserved component kinds, measurement outputs, and provider
|
|
authority flag without importing plugin internals or deciding plugin
|
|
semantics.
|
|
- The web reference now publishes a runtime capability manifest at
|
|
`web/eve-runtime-capability.json`, and the parity harness validates it through
|
|
the same runtime capability path as Unity. Web remains Eve's behavior oracle,
|
|
not an EveWeb split target, unless it gains independent deployment lifecycle.
|
|
Its manifest explicitly claims provider advertisement consumption,
|
|
embedded-document lowering, state bindings, style tokens, authority witnesses,
|
|
plugin projection support, command intent emission, and Chrome headless
|
|
capture evidence.
|
|
- Unity UI Toolkit now declares runtime lifecycle evidence in
|
|
`packages/org.gamecult.eve.unity-uitoolkit/eve-runtime-capability.json`. The
|
|
parity harness validates release, test, and capture lifecycle claims against
|
|
`tools/parity/parity-manifest.json`, checks declared evidence paths, and
|
|
exports lifecycle status through the conformance index. Current proof covers
|
|
incubating UPM package identity, package EditMode tests, Aetheria
|
|
consumer-build smoke, and an Eve-owned batchmode EditMode run through the
|
|
Aetheria Unity project; tagged EveUnity release, moving the batchmode runner
|
|
into EveUnity, and editor or batchmode capture remain explicit split
|
|
blockers.
|
|
- Aetheria now has repeatable Unity EditMode evidence for the Eve UI Toolkit
|
|
runtime. `scripts/run-aetheria-unity-editmode-tests.ps1` temporarily adds
|
|
`org.gamecult.eve.unity-uitoolkit` to Aetheria's Unity `testables`, runs
|
|
`GameCult.Eve.UnityUIToolkit.Tests` in Unity batchmode, writes XML and log
|
|
artifacts under `artifacts/aetheria-unity-editmode`, and restores
|
|
`Packages/manifest.json` before returning. This proves the incubating test
|
|
lifecycle; it does not make Eve own Unity's final runtime lifecycle.
|
|
- Aetheria now has repeatable Unity package consumer-build evidence for the
|
|
Eve UI Toolkit runtime. `scripts/run-aetheria-unity-package-smoke.ps1`
|
|
verifies Aetheria's Unity `Packages/manifest.json` consumes Eve's surface and
|
|
UI Toolkit packages by file reference, checks the generated
|
|
`GameCult.Eve.UnityUIToolkit.csproj` includes all current runtime files, and
|
|
builds the package through Aetheria's Unity-generated project.
|
|
- Unity UI Toolkit now has a first-party `norn.graph` projection-adapter proof
|
|
for `embed.norn`. `NornGraphUiToolkitProjectionAdapter` owns the native
|
|
embedded graph shell and graph command emission path, while the Norn sidecar
|
|
plugin keeps graph layout and graph semantics. EveUnity split-readiness is now
|
|
blocked on runtime-owned release, test, and capture lifecycle evidence rather
|
|
than missing Sai/Norn projection support.
|
|
- Unity UI Toolkit now has a first-party `sai.vn` projection-adapter proof. The
|
|
runtime owns `IEveUiToolkitPluginProjectionAdapter`, registers
|
|
`SaiVisualNovelUiToolkitProjectionAdapter` through
|
|
`EveUiToolkitSurfaceOptions`, and declares support for `vn.stage`,
|
|
`story.choose`, `story.continue`, and `story.jump` in its runtime capability
|
|
manifest. Sai still owns story state and command semantics; Unity only lowers
|
|
the visual stage/dialogue/action surface and emits Eve command requests.
|
|
- Unity UI Toolkit now publishes a runtime-owned capability manifest at
|
|
`packages/org.gamecult.eve.unity-uitoolkit/eve-runtime-capability.json`. The
|
|
parity harness validates that manifest against
|
|
`gamecult.eve.runtime_capability.v1`, cross-checks supported features,
|
|
unsupported Sai/Norn/TeX plugin declarations, command transport schema, and
|
|
incubation metadata, then exports the manifest path and validation errors
|
|
through the conformance report.
|
|
- Aetheria now consumes the exported conformance pack from its own working
|
|
directory through `scripts/run-aetheria-conformance-consumer-smoke.ps1`. The
|
|
smoke asserts the provider pack, `aetheria-world` fixture, `aetheria`
|
|
provider entry, and `aetheria-world-command-replay` scenario without reading
|
|
Eve's parity manifest or dirtying the Aetheria worktree.
|
|
- The parity harness now runs a conformance consumer smoke against a copied
|
|
`artifacts/conformance/latest` layout, proving the export can be consumed
|
|
through `index.json` and `packs/*.json` without reading Eve's parity manifest.
|
|
- The parity harness now emits an `EveConformance`-shaped export under
|
|
`artifacts/conformance/latest`, with a top-level index and per-pack JSON
|
|
files for core, plugin, provider, and runtime consumers.
|
|
- Unity's plugin projection capability gap is now explicitly demoted. The UI
|
|
Toolkit runtime owns generic projection and command requests, while Sai, Norn,
|
|
and TeX semantics remain sidecar-plugin responsibilities. Unity only adds
|
|
projection adapters for capabilities a plugin advertises through Eve.
|
|
- Flutter and Unity now have runtime command-transport smoke evidence in the
|
|
parity report. Flutter emits `gamecult.eve.command.v1` intents from lowered
|
|
controls, and Unity command requests now carry the same command schema.
|
|
- Aetheria now has a provider scenario replay fixture advertised through its
|
|
provider advertisement. The parity harness validates advertised surfaces,
|
|
command boundary consumption, command intents, and provider-owned receipt
|
|
states without importing Aetheria internals into Eve.
|
|
- Sai, Norn, and TeX now have plugin ABI fixtures for describe, validate,
|
|
project, lower, measure, and apply behavior. The parity harness validates
|
|
those fixtures against plugin manifests, so Eve proves the ABI shape without
|
|
owning plugin semantics.
|
|
- Split-readiness reporting now exists for `EveFlutter` and `EveUnity`. The
|
|
parity report lists member runtime health, required plugin capability claims,
|
|
pending proofs, and blockers before either repo can graduate out of Eve
|
|
incubation.
|
|
- Direct2D is now recorded as an external Fensalir adapter spike, not an active
|
|
Eve runtime. Activation requires recorded `gamecult.eve.surface.v1` fixture
|
|
replay, command emission through the advertised boundary, and Direct2D frame
|
|
capture evidence from Fensalir.
|
|
- Fixture conformance metadata now lives beside each fixture and is validated by
|
|
the parity harness, so the corpus can move toward `EveConformance` without
|
|
relying only on Eve's local manifest layout.
|
|
- The browser reference now has an authority/staleness witness fixture. The
|
|
parity report verifies visible `fresh`, `accepted`, `stale`, `missing`,
|
|
`pending`, `denied`, `predicted`, and `reconciled` states, with provider and
|
|
renderer ownership kept separate.
|
|
- Command descriptor validation now runs for strict fixtures. Sai proves
|
|
`story.*`/`style.patch`; Aetheria proves the daemon command boundary; the web
|
|
lowerer resolves authored `action.command` through the shared Eve command
|
|
intent path.
|
|
- Provider advertisement validation now runs in the parity harness.
|
|
- Repixelizer and Aetheria provider advertisements are checked against
|
|
`gamecult.eve.provider_advertisement.v1`.
|
|
- Aetheria has a minimal provider-owned interactive world fixture in Eve so the
|
|
browser oracle can prove the surface path without owning Aetheria truth.
|
|
|
|
## Stop Conditions
|
|
|
|
Stop adding features and update the map when:
|
|
|
|
- a runtime needs product knowledge to render a generic surface;
|
|
- a plugin fixture needs provider state to prove plugin behavior;
|
|
- a provider fixture becomes necessary for core Eve tests;
|
|
- a compatibility route becomes easier to use than a provider advertisement;
|
|
- a generated report says "active" while listing missing source symbols,
|
|
features, metadata, or plugin support;
|
|
- a split target exists but the owner, inputs, outputs, and release lifecycle
|
|
are still awkward to explain.
|
|
|
|
If the sentence "X owns Y so that Z remains true" cannot be written cleanly, the
|
|
migration step is not ready. The machine may still be useful. It is not yet
|
|
coherent.
|