Aetheria/AGENTS.md

# Aetheria Agent Instructions

This repo is mid-migration toward CultMesh-native gameplay state. Treat access
simplicity as an architectural requirement, not a nice-to-have.

## Canonical Typed State

- Default to one canonical shared typed document for each gameplay state concept.
  The daemon may own authority over that document, but it must not imply a
  separate private daemon truth plus a copied client-facing state document.
- The shared runtime assembly defines the document. The daemon mutates/publishes
  it. Unity, Electron, tools, tests, and later runtimes read the same document
  type through CultMesh.
- Client input should feel like grabbing a managed typed state handle and either
  reading it for display or writing/submitting through it according to authority
  policy. Prediction, debounce, routing, quorum, reconciliation, and smoothing
  are CultMesh responsibilities.

Use projections only when the state shape is intentionally different:

- hidden-information filtering;
- expensive or shared derived aggregation;
- viewport/windowed selection;
- SoA/native render or physics layout;
- lossy UI summaries;
- Eve/CultUI surface documents;
- compatibility mirrors with a named removal stage.

"The client needs to see it" is not a projection reason.

## Access Simplicity

- A UI-only inline value should be derived from already accessible typed state.
- A shared UI read should usually be: define the typed document, then read it
  with `client.State.Reactive<TDocument>()` or `client.State.Latest<TDocument>()`.
- A simulation feature should usually be: define the canonical typed document,
  let daemon authority mutate/publish it, then read or modify that same managed
  document from clients according to authority policy.
- Add named handles only when type alone cannot identify the state, such as
  parameterized viewport/detail documents, multiple documents sharing one CLR
  type, semantic query identity, operation policy, or native view ownership.

## Heretek Shape

The facade/projector/adapter/surface-builder chain is heretek now. Do not add a
stack of translation layers to recover one typed domain value.

One adapter at a true boundary is allowed:

- Unity GameObject presentation;
- Eve/CultUI lowering;
- legacy import;
- persistence;
- native view ownership.

Two or more translation layers in a row mean the code is missing a CultMesh
primitive, generated typed handle, canonical document, query surface, operation
handle, state pointer, or native view descriptor.

## Verifier Discipline

The verifier should encode the desired architecture, not the current accidental
shape. When removing old access paths, add checks that reject their return. Do
not write verifier rules that require wrapper/session/facade/projector chains as
proof of correctness.

Good verifier pressure:

- client code owns `CultMeshReactiveDocument<TDocument>`;
- client code reads `.Current`;
- client code uses generic typed document access where possible;
- hot render paths use named SoA/native views;
- operations are typed and authority-aware;
- legacy adapters are quarantined and named for deletion.

Bad verifier pressure:

- requiring `LatestFoo()`/`ReactiveFoo()` wrappers for single fixed documents;
- requiring one-document session wrappers;
- requiring facade/projector/adapter/surface-builder chains;
- treating renderer-local facade indexes as gameplay-state APIs.