diff --git a/README.md b/README.md index e92d92f..7516a99 100644 --- a/README.md +++ b/README.md @@ -156,6 +156,8 @@ payloads as `mimir.eve_media_observation.v1`. See `docs/cultmesh-streaming-ui-framework.md` for the target architecture. See `docs/repo-strategy.md` for the kernel/plugin/runtime/provider ownership boundary and graduation rules. +See `docs/eve-migration-roadmap.md` for the staged migration from in-repo +incubation to kernel, plugin, runtime, conformance, and provider-owned repos. See `docs/renderer-parity.md` for current browser/iOS/Android/Fensalir/Flutter renderer parity. See `docs/surface-contract-v1.md` for the shared CultUI/CultMesh surface and diff --git a/docs/eve-migration-roadmap.md b/docs/eve-migration-roadmap.md new file mode 100644 index 0000000..5dc1b8c --- /dev/null +++ b/docs/eve-migration-roadmap.md @@ -0,0 +1,299 @@ +# 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. +- 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 JSON schemas for plugin manifest and plugin advertisement. +2. Add provider advertisement checks to the parity harness. +3. Add command descriptor checks to fixtures and runtime source-symbol + expectations. +4. Add authority/staleness witness fixture to browser reference. +5. Add conformance-pack metadata files beside fixtures. +6. Add a Direct2D adapter spike or explicitly demote Direct2D until Fensalir owns + the body. +7. 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.