Document canonical CultMesh access rules

This commit is contained in:
Meta Vens 2026-06-29 00:28:12 +01:00
commit 8a76e4f9fb
9 changed files with 317 additions and 89 deletions

View file

@ -1,10 +1,11 @@
# Aetheria Verse Client Contract
Aetheria clients should enter the runtime through CultMesh typed state, not through
daemon internals. The daemon owns simulation authority and publishes daemon state
as Verse records. Unity, tools, test harnesses, and later non-Unity clients open
the same state store with the same runtime document registry and read/write typed
documents through CultNet.
daemon internals. The daemon owns simulation authority over canonical shared
documents; it does not own a separate private truth that is then copied into
client state. Unity, tools, test harnesses, and later non-Unity clients open the
same state store with the same runtime document registry and read/write the same
typed documents through CultMesh/CultNet according to authority policy.
The ergonomic contract is stricter than "typed records are available
somewhere." A client must be able to ask CultMesh for the domain state it wants
@ -14,6 +15,14 @@ through daemon frames, projected rows, record keys, schema slots, state refs,
renderer-local facade indexes, or transport route decisions to reconstruct one
gameplay value.
The default implementation contract is one canonical document type per gameplay
state concept. If `AetheriaRuntimeFooDocument` is the gameplay state, that is
the document the daemon mutates/publishes and the document clients receive from
the shared assembly. A separate projected document exists only when the shape is
intentionally different: hidden-info filtering, expensive aggregation, viewport
windowing, SoA/native layout, lossy UI summaries, surface documents, or a named
compatibility bridge. "The client needs to see it" is not a projection reason.
The shared entrypoint is `AetheriaRuntimeVerseClient` in the runtime state
package. It opens a local `CultMeshNode` with the runtime-only Aetheria contract
registry and exposes:
@ -55,11 +64,11 @@ handles:
using var verse = await AetheriaRuntimeVerseClient.OpenAsync(statePath, "tool-client");
var aetheria = verse.Aetheria();
using var inventory = aetheria.Current.Inventory.Watch(RenderInventory);
using var docking = aetheria.Current.Docking.Watch(RenderDocking);
using var dockingBay = aetheria.Current.DockingBay.Watch(RenderDockingBay);
using var inventory = aetheria.State.Reactive<AetheriaRuntimeInventoryDocument>(entityIndex);
using var docking = aetheria.State.Reactive<AetheriaRuntimeCurrentDockingDocument>();
using var support = aetheria.State.Reactive<AetheriaRuntimeStationSupportDocument>();
var stationRefit = await aetheria.Station.Refit.LatestAsync();
var stationRefit = await aetheria.State.LatestAsync<AetheriaRuntimeStationRefitDocument>();
var visibleObjects = await aetheria.Zone(currentZoneId)
.Objects
.VisibleToCurrentPlayer()
@ -73,6 +82,13 @@ Verse, bind an Eve state pointer, or expose a native slab view. That decision is
CultMesh infrastructure. The caller gets a typed domain value and diagnostics
when it asks for them.
Client input follows the same rule. When a runtime has authority or prediction
rights, mutating the managed typed document is the ergonomic target; CultMesh
debounces, routes, records the prediction, and reconciles against canonical
state. When a runtime does not have direct write authority, it submits a typed
operation handle that the daemon validates and applies to the same canonical
document.
Unity should treat the client as its Aetheria-facing runtime surface. It can
still use Burst, DOTS rendering, and native views for presentation, but the state
authority boundary is the typed CultMesh contract. No Unity-facing code should

View file

@ -5,13 +5,15 @@ Date: 2026-06-28
This guide describes the target developer experience for adding Aetheria state
with CultMesh. If the workflow grows into a chain of facades, sessions,
projectors, adapters, and surface builders, stop and simplify the state API.
That chain is heretek now: it means the feature is compensating for a missing
typed document, query, operation, pointer, native view, or generated handle.
The rule is blunt:
```text
small UI-only value: derive it inline from already accessible typed state
named UI-only projection: define the projected document, then read it
simulation feature: define simulation state, publish typed state, consume it
simulation feature: define one canonical typed document, let daemon authority mutate it, consume the same document everywhere
hot rendering/physics: use SoA, not object-graph UI documents
```
@ -19,6 +21,36 @@ CultMesh owns document identity, sync, prediction, reconciliation, and reactive
access. Aetheria code should read like it is using game state, not walking
protocol layers.
## Canonical Document Rule
The default shape is one shared typed document contract.
```text
AetheriaRuntimeFooDocument
-> daemon authority mutates/publishes it
-> Unity/Electron/tools read the same document type
-> authorized clients write intent or predictions through the managed handle
```
Do not split a feature into "daemon truth" and a separate "CultMesh typed
state" unless the second shape is intentionally different. The assembly is
shared, so the document the daemon owns is also the document clients receive.
Across runtimes, callers should feel like they are grabbing a handle on typed
state and either reading it for display or writing to it for client input.
A second document is justified only when it earns a distinct job:
- hidden-information filtering;
- expensive or shared derived state;
- viewport/windowed selection;
- SoA/native render or physics layout;
- lossy presentation summaries;
- UI surface documents;
- compatibility mirrors with a named removal stage.
Projection is not the normal way to make state client-visible. Projection is an
exception for a different shape.
## The Ergonomic Bar
UI-only state should take one or two steps.
@ -27,7 +59,7 @@ Use one step when the value is small and already derivable from state the caller
has:
```csharp
var currentDocking = client.State.Current.ReactiveDocking();
var currentDocking = client.State.Reactive<AetheriaRuntimeCurrentDockingDocument>();
var bayName = currentDocking.Current?.DockingBayName ?? "";
```
@ -35,16 +67,16 @@ Use two steps when the projection is shared, non-trivial, or should have a
stable schema:
```text
1. Define the daemon-projected typed document.
1. Define the typed projected document.
2. Read it from Unity as a managed reactive typed document.
```
Simulation state should take two or three steps:
```text
1. Put the simulation data and rules in the daemon-owned domain model.
2. Publish the useful client-facing shape as typed CultMesh state.
3. Read that state from Unity and send typed operations back when input mutates truth.
1. Define the canonical typed document in the shared runtime package.
2. Let the daemon mutate/publish that document as the authority for the Verse.
3. Read or modify the same managed document from clients according to authority policy.
```
Anything beyond that needs a clear reason. Performance-sensitive entity
@ -86,7 +118,11 @@ daemon document -> session -> facade -> projector -> adapter -> surface builder
```
That shape preserves reconstruction-era scaffolding. It does not express the
game.
game. At most, one boundary adapter may exist at an actual boundary: Unity
GameObject presentation, Eve/CultUI lowering, legacy import, persistence, or
native view ownership. If two or more layers appear in a row just to obtain one
domain value, stop and move the missing primitive into CultMesh/CultLib or the
generated Aetheria handle surface.
## Choosing The State Shape
@ -105,18 +141,21 @@ Use a projected typed document when:
- the result needs a stable schema or cross-runtime binding;
- the projection should update reactively as daemon state changes.
Use daemon-owned simulation state when:
Use a canonical simulation document when:
- the value affects game rules;
- input can mutate it;
- it needs authority, replay, persistence, or reconciliation;
- the daemon must validate operations before publishing the next state.
Use a projected typed document when the caller needs a different state shape,
not merely because a client needs to see daemon-owned state.
Use SoA/native views when:
- Unity jobs, Burst, Ymir, or rendering need large columnar data;
- row count and per-frame access make object graphs the wrong format;
- the data is a hot view over daemon truth rather than a UI document.
- the data is a hot view over canonical simulation state rather than a UI document.
## One-Step UI Derivation
@ -140,7 +179,8 @@ public sealed class DockingBadge : IDisposable
{
get
{
_docking ??= _client.State.Current.ReactiveDocking();
_docking ??= _client.State
.Reactive<AetheriaRuntimeCurrentDockingDocument>();
var current = _docking.Current;
return current?.IsDocked == true ? current.DockingBayName : "";
}
@ -162,6 +202,11 @@ document.
Use this for shared presentation state such as player HUD, docking summary,
commander wave status, station service summary, or Starbridge support alerts.
Before adding this projection, ask whether the UI can read the canonical
simulation document directly. If it can, do that. The projection exists only
when the UI shape is genuinely derived, filtered, windowed, or shared enough to
deserve its own schema.
### Step 1: Define The Projected Document
Put the document type in the shared runtime package so every runtime sees the
@ -195,20 +240,17 @@ public sealed class AetheriaRuntimeZoneDefenseStatusDocument
}
```
Then expose it as a named projection from `AetheriaClientState`:
Then make it available through generic managed state access:
```csharp
public CultMeshReactiveDocument<AetheriaRuntimeZoneDefenseStatusDocument>
ReactiveZoneDefenseStatus()
{
return Mesh.Reactive<AetheriaRuntimeZoneDefenseStatusDocument>(
AetheriaRuntimeDaemonDocuments.ZoneDefenseStatus);
}
using var status =
client.State.Reactive<AetheriaRuntimeZoneDefenseStatusDocument>();
```
The exact registration/publishing code belongs in the runtime plumbing. It
should be generated or centralized. The feature author should not have to write
five separate access classes for one projected state shape.
five separate access classes, wrapper methods, sessions, or facades for one
projected state shape.
### Step 2: Read It From Unity
@ -230,7 +272,8 @@ public sealed class ZoneDefenseHud : IDisposable
public void Refresh()
{
_status ??= _client.State.ReactiveZoneDefenseStatus();
_status ??= _client.State
.Reactive<AetheriaRuntimeZoneDefenseStatusDocument>();
var status = _status.Current;
if (status == null)
return;
@ -256,25 +299,10 @@ Use this when the feature changes gameplay: heat support, repair drones,
station construction, scenario progression, commander infrastructure, or wave
director state.
### Step 1: Put Truth In The Daemon
### Step 1: Define The Canonical Document
Simulation truth lives with the daemon domain model and tick/apply logic.
```csharp
public sealed class StationSupportState
{
public double CoolingReserve { get; set; }
public double RepairNaniteReserve { get; set; }
public int ActiveSupportDrones { get; set; }
}
```
The daemon mutates this state during ticks and command application. Unity does
not own gameplay truth.
### Step 2: Publish Typed CultMesh State
Expose the client-facing shape as a typed document.
Simulation truth is the shared typed document. The daemon owns authority over
that document, but the document contract is not daemon-private.
```csharp
[MessagePackObject]
@ -292,21 +320,26 @@ public sealed class AetheriaRuntimeStationSupportDocument
}
```
The daemon publishes this document from its current truth. CultMesh handles sync.
If the client has prediction authority, local changes to the managed document
are predictions; reconciliation corrects them without requiring feature code to
### Step 2: Let The Daemon Own Authority
The daemon validates operations, applies ticks, and publishes the canonical
document into the Verse. Unity does not own gameplay truth, but Unity does not
need a separate client-facing copy either. CultMesh handles sync. If the client
has prediction authority, local changes to the managed document are
predictions; reconciliation corrects them without requiring feature code to
manually shuttle deltas.
### Step 3: Read State And Submit Typed Operations
### Step 3: Read Or Mutate Through The Managed Handle
Unity reads state through the managed typed document:
Unity reads the same document through the managed typed handle:
```csharp
var support = client.State.ReactiveStationSupport();
var support = client.State.Reactive<AetheriaRuntimeStationSupportDocument>();
var cooling = support.Current?.CoolingReserve ?? 0;
```
Unity asks the daemon to mutate truth through a typed operation:
When the client does not have direct simulation authority, it submits a typed
operation:
```csharp
client.Operations.Submit(new AetheriaRuntimeDeploySupportDroneOperation
@ -320,6 +353,11 @@ client.Operations.Submit(new AetheriaRuntimeDeploySupportDroneOperation
The daemon validates and applies the operation. The next published document is
the authoritative result.
When the client has prediction or simulation authority, the ergonomic target is
even simpler: modifying the managed reactive document records a prediction,
debounced by the update frame, and CultMesh routes/reconciles it according to
the Verse authority policy.
## SoA For Hot Paths
Use SoA when Unity needs fast columnar access, not when a UI needs a label.
@ -340,9 +378,9 @@ Bad SoA candidates:
- player settings;
- station service summary.
SoA should be a named high-performance view over daemon truth. It should not
force ordinary presentation code to understand frame slabs, column handles, or
native buffer ownership.
SoA should be a named high-performance view over canonical simulation state. It
should not force ordinary presentation code to understand frame slabs, column
handles, or native buffer ownership.
## Reconnection
@ -373,13 +411,13 @@ For projected UI documents, test:
- projection from representative daemon state;
- empty/default state;
- reactive update after source state changes;
- Unity caller reads the projected document directly.
- Unity caller reads the typed document directly.
For simulation features, test:
- daemon tick/application mutates truth;
- daemon tick/application mutates the canonical typed document;
- typed operation validation accepts and rejects correctly;
- published document reflects daemon truth;
- clients read the same shared document type the daemon publishes;
- prediction/reconciliation behavior when the runtime supports local authority;
- reconnect can reconstruct the required player state.
@ -401,8 +439,9 @@ Good verifier expectations:
```text
Unity caller owns CultMeshReactiveDocument<TDocument>
Unity caller reads .Current
Unity caller uses client.State.ReactiveFeatureName()
Unity caller uses client.State.Reactive<TDocument>()
Unity caller submits typed operations for mutations
authorized caller mutates managed typed state as prediction/input
hot renderer uses named SoA view
```
@ -413,6 +452,7 @@ Unity caller owns AetheriaRuntime*Session for one document
Unity caller calls ObserveFeatureName() wrapper only to read Current
UI caller reads raw daemon frames and joins rows
feature adds facade/projector/adapter/surface-builder chain
feature introduces multiple translation layers to get one typed value
```
The verifier should make the codebase harder to regress into ceremony, not
@ -425,8 +465,8 @@ Before calling a CultMesh feature ergonomic, answer these questions:
- Can a UI-only inline value be implemented in one local derivation?
- Can a shared UI projection be implemented by defining the document and reading
it from Unity?
- Can a simulation feature be explained as daemon truth, typed state, typed
operation?
- Can a simulation feature be explained as one canonical typed document plus
authority policy and typed operations?
- Does Unity code read domain state instead of protocol plumbing?
- Is SoA reserved for hot paths?
- Did the verifier protect the clean path instead of the old wrappers?

View file

@ -10,8 +10,9 @@ ambushed by half-finished architecture.
The short version: Unity is being reduced to a renderer, input surface, and
editor environment. Durable game state and portable gameplay facts now live in
typed CultCache/CultNet/CultMesh records under `Aetheria.State`. The daemon is
the simulation owner. Unity and the Electron RTS client are clients of the same
typed Verse state.
the authority over canonical shared documents, not a private truth source that
exports a second client copy. Unity and the Electron RTS client are clients of
the same typed Verse state.
## Start Here
@ -29,8 +30,9 @@ Read these in this order:
5. `docs/aetheria-verse-client-contract.md`
Intended client contract: use typed Verse state, not daemon internals.
6. `docs/cultmesh-feature-implementation-guide.md`
Step-by-step guide for adding daemon-owned typed state, publishing it through
CultMesh, and consuming/interacting with it from Unity.
Step-by-step guide for adding canonical typed state once, letting daemon
authority own mutation, and consuming/interacting with the same document from
Unity and other clients.
7. `Aetheria.State/docs/verse-authority-implementation-plan.md`
Authority and Starbridge staged implementation map.
@ -186,8 +188,12 @@ Expected recurring warnings:
### State Owner
Typed CultCache/CultNet/CultMesh documents are the state owner. The primary
world file is:
Typed CultCache/CultNet/CultMesh documents are the state owner. For normal
gameplay features, define one canonical shared document and let authority policy
decide who may write or predict it. Do not create "daemon truth" plus a separate
client-facing copy unless the second document is intentionally filtered,
aggregated, windowed, lossy, SoA/native, or a named compatibility bridge. The
primary world file is:
```text
GameData/aetheria-world.cc
@ -220,14 +226,15 @@ Use `AetheriaClient` first:
Packages/org.gamecult.aetheria.state/Runtime/AetheriaClient.cs
```
It exposes named reads such as current entity, current docking, station/refit,
sector map, viewport, Starbridge summary, health, authority policy, and SoA
views. It also exposes typed controls through `AetheriaControl` and typed UI
surface helpers through `AetheriaUi`.
It exposes generic managed document reads such as `State.Latest<TDocument>()`
and `State.Reactive<TDocument>()`, parameterized handles for viewport/detail
documents, Starbridge seat handles, typed controls through `AetheriaControl`,
and typed UI surface helpers through `AetheriaUi`.
If a Unity panel or Electron surface needs a fact, prefer adding or extending a
named facade read. Avoid handing callers raw daemon frames unless the caller is
a transitional projection layer.
If a Unity panel or Electron surface needs a fact, prefer the generic managed
document call first. Add a named facade only when it carries semantic identity,
parameters, operation policy, or a distinct derived/native shape. Avoid handing
callers raw daemon frames unless the caller is a transitional projection layer.
### Unity Shell
@ -373,6 +380,12 @@ Work on Ymir/physics:
Git preserves history. The migration should delete dead shims when the typed
replacement exists and tests prove it.
8. Treat facade/projector/adapter/surface-builder chains as a design failure.
One adapter at a true boundary is fine. Stacked translation layers used to
recover one typed value mean the code is missing a CultMesh primitive,
generated handle, canonical document, query, operation, pointer, or native
view.
## Known Transitional Debt
These are not surprises; they are known pressure points.
@ -407,9 +420,13 @@ Use this checklist before writing code:
Add or extend a MessagePack/CultNet document in the runtime package. Use
explicit `[Key]` slots and stable names.
3. Add a facade read or operation.
Prefer `AetheriaClient`, `AetheriaControl`, or `AetheriaUi` over direct
low-level Verse calls in client code.
3. Add the simplest access path.
Prefer `AetheriaClient.State.Latest<TDocument>()` or
`AetheriaClient.State.Reactive<TDocument>()` for canonical documents. Add a
named handle only when type alone cannot identify the document, such as
parameterized viewport/detail state or multiple documents sharing one CLR
type. Use `AetheriaControl` or `AetheriaUi` for typed operations and UI
commands.
4. Lower Unity and Electron through the same semantics.
Unity and RTS do not need identical UI, but they should observe the same
@ -498,8 +515,9 @@ The useful way to look at it is:
When in doubt, follow the typed state:
```text
document -> facade -> client presentation
command document -> daemon apply -> projected result
canonical document -> managed CultMesh handle -> client presentation/input
typed operation -> daemon authority -> same canonical document
projection/native view -> only when the shape is intentionally different
```
If a path does not fit that shape, it is probably transitional debt or a bug.