Document Eve surface authority contracts

This commit is contained in:
Meta Vens 2026-07-08 07:40:51 +01:00
commit a3c9dcd2a0
7 changed files with 198 additions and 57 deletions

View file

@ -132,18 +132,19 @@ Fensalir Direct2D:
## Current Proof
The current iOS app consumes Mimir's `/eve/deck` WebSocket broker. That broker is
already shaped like the future API: provider manifests, retained dashboard
state, provider switching, commands, and typed node metadata. The VoidBot
provider proves that Eve can render an app-specific native cockpit from a
structured mesh snapshot: CTB rail, avatar images, selected Persona/status pane,
state tree, and detail panel.
The current native app consumes Mimir's dashboard WebSocket lowering for retained
dashboard state. That lowering is shaped like the future API: retained dashboard
state, provider switching, commands, and typed node metadata. It is a renderer
path over daemon-owned state, not provider discovery authority. Live provider
discovery belongs to Odin/CultMesh advertisements.
The Android proof under `android/` builds directly against the installed Android
SDK and runs on Periwinkle. It is deliberately small: display Eve's role, poll
the Mimir broker health endpoint, and show timestamped motion/touch samples.
It is a device-edge proof while the browser reference and Flutter/native shared
client are still being cut.
SDK and runs on Periwinkle. It is deliberately small: display Eve's role, render
a configured CultMesh dashboard lowering when one is provided, and capture
timestamped motion/touch/media samples. It does not bake in Mimir dashboard or
sensor URLs; missing discovery stays visible until Odin/CultMesh provides the
endpoints. It is a device-edge proof while the browser reference and
Flutter/native shared client are still being cut.
The public site now reflects the same pressure. The integrated dossier frames
CultMesh as typed distributed state. The Week 07 damage report records Fensalir

View file

@ -36,22 +36,39 @@ metric "Opacity" bind program.Field(x => x.Layers[1].Opacity)
Today the lower substrate exposes reactive document changes through CultMesh /
CultNet database watch streams. The field-level POCO binding handle is the
next ergonomic cut. Until that lands, Eve documents should still carry explicit
binding descriptors:
next ergonomic cut. Eve documents now carry explicit
`CultMeshStateBindingDescriptor` values on each component so renderers do not
have to infer provider state from string props:
- document schema;
- document id, key, or named handle;
- field path;
- value kind;
- access mode;
- authority label;
- optional command id for writes;
- freshness, prediction, denial, and reconciliation metadata where available.
- `targetProp`, the component prop that receives the live value;
- `pointerId`, the stable typed CultMesh state pointer;
- `sourceId`, the provider/CultMesh source, record, witness, or field id;
- `schemaId`, the state schema;
- `routeKind` and `routeDescription`, so runtimes can prefer in-process,
shared-memory, IPC, network, or WASM paths without app glue.
This keeps the DSL honest. The visual language can name a field; the provider
and CultMesh decide whether that field is readable, writable, predicted,
accepted, denied, stale, or missing.
Commands follow the same rule. Eve command templates carry
`CultMeshOperationBindingDescriptor` values so a button or menu item points at
a typed operation id, optional request schema, label, and route hint. The DSL
may provide friendly `button` sugar, but the compiled surface should not make a
free-floating command string the canonical operation boundary or public
runtime construction path.
When a renderer fires that command, the request carries a
`CultMeshOperationInvocationDescriptor`. That invocation preserves operation id,
request schema, preferred route, and optional idempotency through the renderer
boundary so Aetheria, Bifrost, Unity, Electron, and browser runtimes do not each
invent a local command envelope. The request payload is a
`CultMeshOperationPayload`, so renderers can ingest surface props at the edge
while command handlers read scalar fields through shared typed helpers. New
runtime code should construct requests from the invocation descriptor and
payload primitive directly; raw command strings and dictionary payloads are
serialization details, not live APIs.
Discovery of those backing documents should come from a provider advertisement
when available. See
[provider-advertisement-contract.md](./provider-advertisement-contract.md) for

View file

@ -85,27 +85,65 @@ fixture claiming to render CultUI while the retained tree no longer contains
the partitions, bindings, tokens, or slider anatomy the renderer is supposed to
lower.
The fixture matrix also includes `embedded-surface`, which proves that nested
CultMesh document slots survive the shared surface contract. The web reference,
Flutter parity body, Unity UI Toolkit lowerer, iOS UIKit renderer, and native
Android Kotlin dashboard renderer all need to understand
`surface.slot`/`embeddedDocuments`. Rust participates at the CultMesh document
sync layer: it must preserve the same `gamecult.eve.surface.v1` slot contract
through typed document replication even when it is not painting pixels.
Nested surface support is a required feature for every active GUI runtime in
`tools/parity/parity-manifest.json`. Active runtimes list
`requiredFixtures: ["embedded-surface"]` and
`supportedFeatures: ["embeddedDocuments"]`; the semantic report prints both so a
runtime cannot quietly fall out of the contract. Runtime entries also use
`expectedSourceSymbols` for the renderer files that must contain the slot
lowering path, so a runtime cannot keep a green body merely because its source
file exists. The shared fixture is `web/fixtures/cultui-embedded-surface.json`,
and renderer-specific tests should load that fixture rather than hand-authoring
a local substitute.
## Runtime Status
The harness tracks every target runtime:
- Web reference: active semantic and screenshot target through Chrome headless
using the provider query parameter.
using the provider query parameter. Required nested-surface evidence:
`node --test web\eve-dsl.test.mjs` plus the `embedded-surface` fixture in
`tools/parity/run-parity.mjs`.
- Web responsive layout: Chrome headless emits phone, tablet, and desktop PNGs.
- iOS / UIKit: screenshot target through SSH and EveCanvas'
`/var/mobile/Library/EveCanvas/capture-request` service. Current iOS capture
is fixed-device until a simulator or device-resize adapter exists.
is fixed-device until a simulator or device-resize adapter exists. Required
nested-surface evidence: run `scripts/run-parity-smoke.ps1 -ProviderId
gamecult.eve.embedded-demo` against the device target.
- Windows / Flutter: screenshot target through the Flutter parity golden smoke,
with phone, tablet, and desktop goldens.
with phone, tablet, and desktop goldens. Required nested-surface evidence:
`flutter test --plain-name embedded_surface_fixture_contract` plus
`scripts/capture-flutter-parity.ps1 -FixtureId
gamecult.eve.embedded-demo`.
- Linux / Flutter: screenshot target through Nightwing over SSH. The smoke
stages `flutter/eve_parity`, runs Flutter goldens on Nightwing, and pulls back
phone, tablet, and desktop PNGs.
phone, tablet, and desktop PNGs. Required nested-surface evidence:
`scripts/capture-linux-flutter-parity.ps1 -FixtureId
gamecult.eve.embedded-demo`.
- Android / Flutter: screenshot target through the same Flutter renderer,
packaged as a debug APK, installed on Periwinkle through `adb`, and captured
with optional `adb shell wm size`, orientation control, and `adb exec-out
screencap`; the script restores device size and rotation after each viewport.
- Android / Kotlin device edge: compatibility body for CultMesh dashboard and
sensor experiments. It is not the GUI parity target.
Required nested-surface evidence: `scripts/capture-android-flutter-parity.ps1
-FixtureId gamecult.eve.embedded-demo`.
- Android / Kotlin device edge: lightweight native CultMesh dashboard and
sensor host. Required nested-surface evidence:
`android/app/src/main/java/org/gamecult/eve/MainActivity.kt` renders
`surface.slot` with a content description containing the embedded slot
identity, and `node tools/parity/run-parity.mjs` reports
`embeddedDocuments` support for `android-kotlin`.
- Rust / CultMesh: typed document runtime rather than a CultUI renderer.
Required nested-surface evidence: `cargo test -p cultnet-rs
rust_preserves_cultui_embedded_surface_slots_through_typed_document_sync`
in CultLib.
- Fensalir Direct2D: specialized native target, adapter/capture still missing.
Pending runtimes are allowed. Silent fake parity is not.

View file

@ -167,12 +167,12 @@ Transport routes are separate from service identity:
```json
{
"kind": "cultnet",
"address": "cultnet://10.77.0.4:3075",
"address": "cultmesh://asgard.yggdrasil.streampixels/transport/cultnet",
"carries": [
"asgard.yggdrasil.streampixels/eve/tui",
"asgard.yggdrasil.streampixels/eve/gui"
],
"note": "CultNet reliable UDP route for this located service."
"note": "Odin/CultMesh-discovered CultNet reliable UDP route for this located service."
}
```

View file

@ -17,17 +17,27 @@ enough that Repixelizer remains itself across runtimes.
The shared fixture/report path lives in
[parity-testing-harness.md](./parity-testing-harness.md). That harness is the
current evidence surface for semantic parity and runtime capture gaps.
The nested CultUI surface feature is tracked as fixture `embedded-surface`,
loaded from `web/fixtures/cultui-embedded-surface.json`, and must be understood
by every renderer that claims `gamecult.eve.surface.v1` GUI parity.
Runtime discovery for the feature is in `tools/parity/parity-manifest.json`:
active GUI runtimes advertise `supportedFeatures: ["embeddedDocuments"]` and
require the `embedded-surface` fixture. Native Android/Kotlin makes a narrower
active claim: it preserves and displays embedded slot identity in its dashboard
renderer while Android Flutter remains the responsive screenshot target. Rust
proves the same contract at the CultMesh typed document sync layer.
## Current State
| Renderer | Status | Proof | Gap |
| --- | --- | --- | --- |
| Web reference | Active reference/debug renderer | `web/` renders live VoidBot and fixture surfaces through the provider picker; compiles indentation CultUI; lowers partitions, field rows, and slider anatomy; Chrome headless capture emits phone/tablet/desktop PNGs | Needs command round-trip tests |
| Windows / Flutter | Active shared graphical smoke target | `flutter/eve_parity` loads exported `gamecult.eve.surface.v1` fixture JSON and emits phone/tablet/desktop golden PNGs through `capture-flutter-parity.ps1` | Needs native window capture and tighter text/style normalization |
| Linux / Flutter | Active shared graphical smoke target | Nightwing runs the Flutter parity goldens over SSH and returns phone/tablet/desktop PNGs | Needs native window capture and runner health checks |
| Android / Flutter | Active shared graphical smoke target | The same Flutter parity app is built as an APK, installed on Periwinkle, and captured at phone/tablet/desktop plus native physical panel orientations | Needs live provider picker and command transport beyond fixture assets |
| iOS / UIKit | Active native screenshot target | SSH capture stages selected fixture JSON, EveCanvas renders it, and emits a PNG from `/var/mobile/Library/EveCanvas/latest-screenshot.png` | Needs real scene composition for `vn.stage`, Repixelizer token fidelity, and responsive/simulator capture |
| Android / Kotlin device edge | Compatibility body | Native APK consumes CultMesh dashboard/sensor documents for edge experiments | Not the GUI CultUI parity target unless direct Android ownership earns its keep |
| Web reference | Active reference/debug renderer | `web/` renders local provider advertisements and fixture surfaces through the provider picker; compiles indentation CultUI; lowers partitions, field rows, slider anatomy, and `surface.slot`; Chrome headless capture emits phone/tablet/desktop PNGs | Needs live Odin/CultMesh provider feed and command round-trip tests |
| Windows / Flutter | Active shared graphical smoke target | `flutter/eve_parity` loads exported `gamecult.eve.surface.v1` fixture JSON, including `embedded-surface`, and emits phone/tablet/desktop golden PNGs through `capture-flutter-parity.ps1` | Needs native window capture and tighter text/style normalization |
| Linux / Flutter | Active shared graphical smoke target | Nightwing runs the Flutter parity goldens, including embedded surface slots, over SSH and returns phone/tablet/desktop PNGs | Needs native window capture and runner health checks |
| Android / Flutter | Active shared graphical smoke target | The same Flutter parity app is built as an APK, installed on Periwinkle, and captured at phone/tablet/desktop plus native physical-panel orientations | Needs live provider picker and command transport beyond fixture assets |
| iOS / UIKit | Active native screenshot target | SSH capture stages selected fixture JSON, EveCanvas renders it, and emits a PNG from `/var/mobile/Library/EveCanvas/latest-screenshot.png`; `embedded-surface` is part of the required fixture matrix | Needs real scene composition for `vn.stage`, Repixelizer token fidelity, and responsive/simulator capture |
| Android / Kotlin device edge | Active lightweight renderer | Native APK consumes CultMesh dashboard/sensor documents and preserves `surface.slot` / `embeddedDocuments` identity in the dashboard renderer | Needs automated native dashboard capture |
| Rust / CultMesh | Document-sync contract runtime | CultLib replicates the `gamecult.eve.surface.v1` embedded slot contract through typed document sync | Not a pixel renderer |
| Fensalir Direct2D | Specialized native/game-runtime landing zone | Existing `AquariumUiDocument` and `DirectWriteOverlay` path | Needs adapter from Eve surface document to `AquariumUiDocument`, DirectWrite/Direct2D token lowering, and a clear reason to stay separate from Flutter for desktop UI |
## Spawned Surfaces
@ -35,8 +45,6 @@ current evidence surface for semantic parity and runtime capture gaps.
The browser reference runner now exposes local advertisements through the
provider picker:
- `VoidBot Live`: connects to Mimir's `/eve/deck` broker and opens
`voidbot.swarm`.
- `Repixelizer`: loads `web/fixtures/repixelizer.provider-advertisement.json`
and `web/fixtures/repixelizer.eve-surface.json`.
- `Fensalir Direct2D`: loads `web/fixtures/fensalir-client-surface.json`, a
@ -47,9 +55,11 @@ provider picker:
- `CultUI Inspector`: compiles `web/fixtures/cultui-slider-inspector.eve`
and proves partition/field-row/slider-anatomy lowering in the web reference.
The remaining temporary part is the local provider list itself. The runtime app
target is the same picker fed by live `gamecult.eve.provider_advertisement.v1`
documents through CultMesh/Odin.
The remaining temporary part is the local fixture provider list itself. The
runtime app target is the same picker fed by live
`gamecult.eve.provider_advertisement.v1` documents through CultMesh/Odin; the
browser reference no longer opens live providers by dialing Mimir's deck broker
directly.
Start it with:

View file

@ -79,7 +79,9 @@ Every component has:
"id": "stable.local.id",
"kind": "panel.dialogue",
"props": {},
"children": []
"children": [],
"stateBindings": [],
"embeddedDocuments": []
}
```
@ -102,6 +104,46 @@ If a renderer does not know a specialized kind, it should fall back through the
kind path: `panel.dialogue` may render as `panel`; `image.sprite` may render as
`image`.
`stateBindings` are explicit `CultMeshStateBindingDescriptor` values attached
to component props. They keep provider state identity out of ad-hoc renderer
stores and out of string-only prop conventions. A binding names:
- `targetProp`: component prop receiving the live value, usually `value`.
- `pointerId`: stable typed CultMesh state pointer id.
- `sourceId`: provider/CultMesh source, record, witness, or field id.
- `schemaId`: schema of the source state.
- `routeKind`: preferred locality such as `in-process`, `shared-memory`,
`ipc`, `network`, or `wasm`.
- `routeDescription`: optional diagnostics for tools and operators.
Renderers may still honor compatibility props such as `valueRef`, but new
CultUI/Eve runtimes should use `stateBindings` as the canonical contract and
let the CultMesh runtime resolve, watch, predict, or deny the value. Eve does
not define a parallel binding DTO; the live surface contract imports the shared
CultMesh primitive directly.
### Embedded Documents
`embeddedDocuments` are explicit CultMesh document slots attached to a component.
Use them when a provider wants one surface to own layout while a nested region
remains a separately synced document. Inventory panels, inspectors with live
subdocuments, tab bodies, drag/drop overlays, and remote tool panes should use
slots instead of copying child state into a parent DTO.
Each slot names:
- `slotId`: stable local slot identity inside the parent component.
- `documentId`: CultMesh document id to resolve and subscribe to.
- `schemaId`: expected schema, commonly `gamecult.eve.surface.v1` or a
provider-specific surface document schema.
- `presentationKind`: semantic lowering hint such as `inventory.dropdown`.
- `routeHint`: optional CultMesh locality hint for resolving the child.
Renderers lower normal `children` first, then resolve and mount
`embeddedDocuments` through their CultMesh document resolver. A renderer that
cannot resolve a slot must preserve the slot identity in diagnostics or a
placeholder; it must not invent a local substitute for the child document.
## Embedded Knowledge Surfaces
Eve must be able to place rich interactive surfaces inside another surface. For
@ -216,6 +258,24 @@ Standard command names:
- `transform.rotate`
Providers may add command names, but they must advertise them in `commands`.
Live Eve command templates carry `CultMeshOperationBindingDescriptor` values:
the operation id is the canonical command identity, `schemaId` may name the
typed request body, `label` names the visible affordance, and `routeHint`
describes the preferred invocation locality. Compatibility fields such as
`command` and `transport` may still be projected for old renderers, but they
are not the authoritative live command model and should not appear as public
runtime construction APIs.
Renderer command requests carry `CultMeshOperationInvocationDescriptor` values.
That invocation descriptor is the canonical operation identity at click/change
time and preserves request schema, preferred route, and optional idempotency.
Renderer command requests also carry `CultMeshOperationPayload`, a shared
payload value with typed scalar readers. Legacy `command` strings and string
payload fields may be serialized while old documents migrate, but live
CultUI/Eve runtimes route from the shared CultMesh invocation descriptor and
read scalar fields through the shared payload primitive. Renderer code should
construct requests from `CultMeshOperationInvocationDescriptor` and
`CultMeshOperationPayload`, not from command strings plus raw dictionaries.
## Synchronized Style