Thing/docs/plugin-architecture.md

# Eve Plugin Architecture

Eve should be a presentation kernel, not a presentation monorepo.

The repo currently contains several renderer bodies because they were useful
proof vehicles: browser reference, iOS/UIKit, Android/Kotlin, Flutter parity,
Unity packages, and fixture lowerers. That does not mean every renderer,
domain representation, and product client should live in Eve forever. The
durable architecture is smaller and sharper:

- Eve core owns the surface/control contract.
- Plugins own domain representation semantics.
- Renderer clients own runtime substrate.
- Providers own accepted state and side effects.
- Odin/CultMesh owns discovery and routing.

The kernel should be boring enough that new renderers can prove conformance
without joining a single giant repo, and domain plugins can add expressive
surface kinds without forcing Eve core to absorb every product vocabulary.

## Authority

Eve core owns:

- `gamecult.eve.surface.v1` and related surface schemas;
- `gamecult.eve.command.v1` and operation binding/invocation descriptors;
- CultUI authoring and lowering contracts;
- plugin manifest schema and discovery rules;
- renderer capability reporting;
- conformance and parity harness expectations;
- core component kinds that are genuinely cross-domain.

Plugins own:

- domain component kinds;
- domain command semantics;
- domain state projection rules;
- plugin-local fixtures and conformance cases;
- compatibility adapters for existing libraries or products.

Renderer clients own:

- native projection into their runtime;
- input capture and command emission;
- local sensor/media capture when relevant;
- runtime-specific capability gaps;
- screenshots, frame capture, and performance telemetry.

Providers own:

- live state;
- command acceptance or refusal;
- receipts;
- reconciliation;
- side effects.

Odin/CultMesh owns:

- provider advertisement discovery;
- plugin advertisement discovery;
- document routing;
- freshness and availability view;
- replay/subscription substrate.

## Why Not A Monorepo

The monorepo path is tempting because Eve already has several client bodies.
It would make local edits easy at first: add Sai, absorb Aetheria's Electron
client, add Unity full-scene lowering, add Godot, add Direct2D, keep everything
under one Makefile. That is how a kernel becomes a warehouse with a logo.

The long-term costs are worse:

- Unity, Electron, Godot, Swift/UIKit, Kotlin/Android, Flutter, browser, and
  native Direct2D have different build systems and failure modes.
- Product semantics such as visual novels, RTS overlays, ARPG world-space HUDs,
  graph maps, proof fields, and sensor fusion views change at different speeds.
- Renderer clients need to release, test, and deploy independently.
- A domain plugin should be able to evolve without asking every renderer body
  to accept its source tree.
- Eve core should stay small enough that a renderer author can understand the
  contract without learning every GameCult product.

Eve can keep reference implementations and first-party packages while the
contract forms. The target is not "everything leaves Eve tomorrow." The target
is "nothing joins Eve core unless it protects a core invariant."

## Plugin Model

An Eve plugin extends the representation vocabulary. It does not become a
provider and does not accept commands on behalf of an app.

Plugin responsibilities:

- declare component kinds it introduces;
- declare command names or operation descriptors it introduces;
- declare state document schemas it can project or consume;
- provide renderer-agnostic semantics for those kinds;
- provide fallback behavior when a renderer lacks support;
- provide fixtures for the parity harness;
- optionally provide reference lowerers for web or another runtime.

Plugins may be distributed as separate repos, package artifacts, or in-repo
packages during incubation. The ownership rule is semantic, not packaging
ceremony: the plugin owns the representation shape, while providers own live
state and renderer clients own projection.

### Example Plugin Manifest

```json
{
  "schema": "gamecult.eve.plugin.v1",
  "pluginId": "sai.vn",
  "title": "Sai Visual Novel",
  "owner": "sai",
  "version": "0.1.0",
  "componentKinds": [
    "vn.stage",
    "panel.dialogue",
    "text.dialogue",
    "rail.actions"
  ],
  "commands": [
    {
      "command": "story.continue",
      "schema": "sai.vn.story_command.v1",
      "effect": "advance-story"
    },
    {
      "command": "story.choose",
      "schema": "sai.vn.story_command.v1",
      "effect": "choose-branch"
    },
    {
      "command": "story.jump",
      "schema": "sai.vn.story_command.v1",
      "effect": "jump-to-knot"
    }
  ],
  "stateSchemas": [
    "sai.vn.story_session.v1",
    "sai.vn.visual_manifest.v1"
  ],
  "fixtures": [
    {
      "fixtureId": "sai.vn.basic-scene",
      "schema": "gamecult.eve.surface.v1",
      "path": "fixtures/basic-scene.surface.json"
    }
  ],
  "capabilities": {
    "requires": [
      "image.background",
      "control.button"
    ],
    "optional": [
      "embed.norn",
      "embed.tex",
      "scene.placement.keystone"
    ]
  }
}
```

The exact fields can change, but the invariant should not: plugin metadata
must be enough for Eve, Odin, and renderer clients to know what semantics are
being introduced, what fixtures prove them, and what capability gaps must be
reported instead of hidden.

## Discovery

There are two different discoveries. Do not collapse them.

Provider discovery answers:

> What live thing owns state and accepts commands?

Plugin discovery answers:

> What representation vocabulary and command semantics are needed to render
> and interact with this surface correctly?

Provider advertisements remain `gamecult.eve.provider_advertisement.v1`.
Plugin advertisements should be a separate document family,
`gamecult.eve.plugin_advertisement.v1`, or a typed plugin catalog referenced
from provider advertisements.

Recommended discovery path:

1. A plugin publishes a plugin advertisement through CultMesh/Odin or ships a
   local package manifest.
2. A provider advertisement names the plugins its surfaces require.
3. Odin indexes providers and plugins separately.
4. A renderer asks Odin for the provider surface and the required plugin
   manifests.
5. The renderer checks local plugin support.
6. Unsupported required plugin capability becomes a visible capability gap.
7. Optional unsupported capability becomes a visible degraded lowering.

Provider advertisement sketch:

```json
{
  "schema": "gamecult.eve.provider_advertisement.v1",
  "providerId": "aetheria.rts.commander",
  "surfaces": [
    {
      "surfaceId": "aetheria.rts.commander.vn-briefing",
      "schema": "gamecult.eve.surface.v1",
      "requiresPlugins": [
        {
          "pluginId": "sai.vn",
          "versionRange": "^0.1.0",
          "requiredCapabilities": [
            "vn.stage",
            "story.choose"
          ]
        }
      ]
    }
  ]
}
```

Plugin advertisement sketch:

```json
{
  "schema": "gamecult.eve.plugin_advertisement.v1",
  "pluginId": "sai.vn",
  "ownerService": "sai",
  "version": "0.1.0",
  "manifestAddress": "cultmesh://asgard.sai/plugins/vn/manifest",
  "schemas": [
    "sai.vn.story_session.v1",
    "sai.vn.visual_manifest.v1"
  ],
  "componentKinds": [
    "vn.stage"
  ],
  "commands": [
    "story.continue",
    "story.choose",
    "story.jump"
  ],
  "fixtures": [
    "cultmesh://asgard.sai/plugins/vn/fixtures/basic-scene"
  ]
}
```

Local development may use file manifests, but live discovery should flow through
Odin/CultMesh. A renderer must not scrape random repo paths to guess plugin
support.

## Sai As The VN Plugin Owner

Sai should own Eve's VN/Ink representation plugin.

Sai's current body is already crisp:

- static-site Ink loading through `inkjs`;
- visual manifest interpretation;
- DOM rendering for static sites;
- static-site auto-init;
- Eve surface projection through `eve.js`.

Sai should not become a daemon merely because Eve needs VN semantics. Sai can
own the plugin because it understands Ink, visual manifests, choices, story
state, scene assets, and static-site constraints. The active app or provider
still owns live session state and receipts.

Sai plugin responsibilities:

- define `vn.stage` semantics;
- define story state projection shape;
- define `story.continue`, `story.choose`, and `story.jump` semantics;
- define visual manifest schema as Eve-facing representation input;
- define optional embedded scene affordances such as Norn/TeX placement when
  they are used inside VN scenes;
- provide fixtures for Eve parity;
- provide a web/static-site reference implementation.

Sai does not own:

- Aetheria story session state;
- RTS or ARPG command acceptance;
- multiplayer synchronization;
- save/load authority;
- Unity/Electron/Godot renderer bodies;
- CultMesh provider routing.

## Building An App With Eve And Sai

An app that wants VN functionality composes four layers.

1. App provider owns live state.
   For Aetheria, this might be `aetheria.rts.commander` and
   `aetheria.arpg.world`. Each provider owns its own current story/session
   state, save/load integration, eligibility, command acceptance, and receipts.

2. Sai plugin owns VN representation.
   The provider uses Sai's plugin schema to express story state as `vn.stage`,
   choices, speaker, line, scene, sprites, manifest-backed assets, and story
   commands.

3. Eve owns surface/control contract.
   Eve validates that the surface and command descriptors conform to
   `gamecult.eve.surface.v1`, the plugin manifest, and operation binding rules.

4. Renderer client owns projection.
   Electron, Unity UI Toolkit, Unity scene, Godot, browser, or Direct2D lower
   the same surface locally and emit commands back to the provider's advertised
   route.

The app-provider receipt is the proof, not the button click. A Unity ARPG scene
and an Electron RTS shell can both emit `story.choose`; the Aetheria provider
decides whether that command is accepted in that runtime, records the receipt,
and republishes state.

## Aetheria RTS And ARPG Example

Aetheria may need VN functionality in two runtimes:

- RTS layer: commander briefings, dialogue overlays, strategic decisions,
  lore panels, faction negotiations, mission choices.
- ARPG layer: in-world conversations, diegetic prompts, scene dialogue,
  cinematic overlays, localized interaction choices.

Sai should not care which runtime is displaying the VN. Sai should care about
the VN representation:

- current story path/knot;
- speaker;
- dialogue line;
- choices;
- scene/background/sprites;
- visual manifest references;
- story commands;
- optional embedded surfaces.

Aetheria owns the runtime-specific meaning:

- whether a choice is allowed during combat;
- whether a dialogue pauses simulation;
- whether RTS and ARPG sessions share story state;
- whether a choice writes to save state;
- whether multiplayer/authority rules allow the command;
- whether a receipt is visible to the player, operator, or both.

Renderer clients own projection:

- Electron RTS may lower `vn.stage` as a 2D overlay panel or mission briefing.
- Unity UI Toolkit may lower the same surface as a native 2D UI document.
- Unity full-scene renderer may place dialogue in world space or cinematic
  scene space.
- Godot may lower the same plugin semantics into Godot controls or scene nodes.

The shared command path:

```text
renderer click
  -> Eve command envelope
  -> Aetheria provider command route
  -> Aetheria accepts/denies story command
  -> provider writes receipt
  -> provider republishes surface state
  -> renderer updates from provider state
```

No runtime gets to decide the story consequence just because it rendered the
button.

## Renderer Client Repos

Long-term renderer/client bodies should split out when they become real apps:

- `EveElectron2D` or Aetheria-owned Electron client for RTS/editor/operator 2D.
- `EveUnityUIToolkit` for Unity UI Toolkit 2D lowering.
- `EveUnityScene` or Aetheria-owned Unity scene frontend for full game 2D/3D.
- `EveGodot` for Godot lowering.
- `Fensalir` for Direct2D/native runtime lowering if Fensalir remains the body.
- `EveWebReference` can stay in Eve core as the canonical reference renderer
  unless it grows product-specific runtime ownership.

While these live in the Eve repo as proofs, they should behave like clients of
the plugin ABI. They should not be allowed to reach into plugin source or
provider internals as a convenience.

## Conformance

Every plugin needs conformance fixtures. Every renderer that claims plugin
support needs to run them.

For Sai VN:

- basic `vn.stage` scene;
- choice command fixture;
- continue command fixture;
- visual manifest asset fixture;
- embedded Norn/TeX optional fixture;
- degraded renderer fixture for clients without scene placement;
- receipt round-trip fixture driven by a fake provider.

The parity manifest should be extended so runtimes declare plugin support:

```json
{
  "runtimeId": "aetheria.unity.uitoolkit",
  "supportedPlugins": [
    {
      "pluginId": "sai.vn",
      "capabilities": [
        "vn.stage",
        "story.choose",
        "story.continue"
      ]
    }
  ]
}
```

A renderer can be honest without being complete. Unsupported features should
show up as capability gaps, not disappear into a local approximation.

## Repo Strategy

Recommended path:

1. Keep Eve core in `E:/Projects/Eve`.
2. Define `gamecult.eve.plugin.v1` and `gamecult.eve.plugin_advertisement.v1`.
3. Let Sai publish the first domain plugin manifest for VN/Ink.
4. Add Sai VN fixtures to Eve parity as plugin fixtures, not Eve core fixtures.
5. Make the browser reference load plugin manifests and report missing
   capabilities.
6. Spin renderer clients out as they become real bodies.
7. Keep in-repo clients only as references or incubation bodies with explicit
   exit criteria.

Absorbing Sai into Eve is the fallback if the plugin boundary fails. It should
not be the first move. The cleaner machine is Eve as kernel, Sai as VN plugin,
Aetheria as provider, and renderer clients as separate bodies.