300 lines
12 KiB
Markdown
300 lines
12 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 host
|
|
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.
|
|
- 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 host, Android/iOS/desktop
|
|
build flow, native capture, and parity reports.
|
|
- EveUnity: UPM package release, plugin host 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. Add provider advertisement checks to the parity harness.
|
|
2. Add command descriptor checks to fixtures and runtime source-symbol
|
|
expectations.
|
|
3. Add authority/staleness witness fixture to browser reference.
|
|
4. Add conformance-pack metadata files beside fixtures.
|
|
5. Add a Direct2D adapter spike or explicitly demote Direct2D until Fensalir owns
|
|
the body.
|
|
6. Add split-readiness reports for EveFlutter and EveUnity.
|
|
|
|
## 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.
|