Ymir/docs/architecture.md

Ymir Architecture

Objective

Expose Box3D as authoritative, typed, persistent GameCult physics without leaking an alpha native API into products, clients, or durable state.

Ymir's target is a stable embedded wrapper around retained Box3D worlds, not an independent physics-engine research project. Box3D supplies the physics mind. Ymir supplies the memory, nerves, names, and session boundary. The same boundary may optionally be hosted as a standalone daemon.

Target Owner

A long-lived Box3D b3World owns the physical decision: given the current world plus commands for a fixed step, what transforms, velocities, overlaps, casts, and contact transitions are true.

Ymir owns the enclosing session and contract:

• pin and build the accepted Box3D release;
• map stable GameCult ids to transient Box3D handles;
• accept typed body, shape, filter, force, torque, field, query, and step commands;
• project Box3D outputs into typed, deterministically ordered Ymir facts;
• reconstruct sessions from CultCache checkpoints;
• return typed state, contacts, queries, and receipts to an embedding product;
• when running standalone, publish Ymir's own physics provider and operator surfaces through CultMesh;
• supervise world lifetime, failure, replay, and observability.

Deployment Boundary

For Aetheria, Ymir is an embedded library. Aetheria owns the outer daemon, gameplay session, fixed tick, product commands and receipts, asset catalog, and advertised Eve/CultMesh surface. Generic Eve clients connect directly to the Aetheria daemon. They never import Ymir internals and do not route gameplay through a standalone Ymir or discovery service.

A standalone Ymir daemon is an optional hosting mode for physics tooling and other products. It hosts the same Ymir session primitive; it is not an Aetheria relay and cannot own a shadow copy of Aetheria's world.

Current Body

The runtime solver cut is complete: Box3D is the only integrator, collision engine, broadphase, query-geometry implementation, and contact source in the committed Ymir path. The public YmirSimulator.Step compatibility API creates an isolated internal session for one complete snapshot, projects its output, and disposes it. Public circle overlap and cast APIs invoke Box3D geometry over caller-supplied bodies.

The retained native session now has a public in-process YmirSession port with explicit spawn, remove, teleport, velocity, configuration, force, torque, step, and disposal operations. It emits revisioned receipts and typed Begin/Hit/End facts with stable Ymir identities. Ordinary retained steps do not accept complete body snapshots.

The embedded retained-session library has replay-backed reconstruction, durable command receipts, incremental journal-suffix capture, and bounded resume descriptors. Aetheria stores these in a second daemon-private CultCache: immutable chunks are flushed first, immutable per-frame resumes second, and the public Aetheria frame last. The public frame is the only commit marker. Orphaned private records cannot advance gameplay truth, and restart fails closed once the persistence capability has been activated. Complete replay history is not product state and never rides in public client frames. The current CLI still has no named session registry or CultMesh command lowerings; its CultCache output remains a regenerated diagnostic projection.

Target Inputs

• stable body and shape definitions
• fixed time step and explicit substep count
• transient forces, torques, impulses, and target transforms
• collision filters and material definitions
• overlap, ray, and shape-cast queries
• product-owned selections such as which pickup ids a tractor may affect

Aetheria chooses physical intent and gameplay eligibility. Box3D decides geometry membership and contact. Ymir carries the typed handoff.

Target Outputs

• body transforms and linear/angular velocities
• begin, end, and hit contact facts with stable Ymir ids
• overlap and cast results sorted by distance and stable id
• step receipts and replay/checkpoint provenance
• provider-owned operator and debug projections

Box3D callback order is not a public contract. Ymir may sort facts, but it may not alter their membership or invent missing contacts.

Derived State

• Box3D world, body, shape, contact, and joint handles are transient session state derived from stable Ymir definitions.
• CultCache checkpoints are reconstruction inputs and publication records; they are not a second live solver.
• SoA body documents are transport and inspection projections over the live session.
• Unity GameObjects and Electron objects are render state only.
• Aetheria damage, loot, capacity, faction, and scoring consequences are derived from Ymir facts plus Aetheria policy.

Dimensional Compatibility

The fossil Aetheria simulation uses a two-dimensional gameplay plane. During cutover, Ymir maps that plane into Box3D X/Z with translation on Y locked and rotation constrained to the plane normal. This is an explicit compatibility projection. It does not make Ymir a second 2D physics engine.

Sphere friction and inertia are not identical to planar disk behavior. Any mechanic that depends on that difference must be witnessed against the fossil and then expressed through Box3D configuration, not repaired by a parallel solver.

Forbidden Writers

• managed integration, impulse resolution, collision geometry, or broadphase code in Ymir;
• persisted force or torque replayed as if it were continuing authority;
• Aetheria rectangle, capsule, overlap, or contact tests deciding gameplay physics;
• Unity collision callbacks deciding hits, destruction, or pickup collection;
• renderer transforms pushing hidden corrections into the world;
• transport endpoints or dashboards owning world state;
• Box3D opaque ids stored as durable GameCult identity.

Target Shared Paths

Direct player commands, agent commands, programmatic spawns, server ticks, imports, reconnects, replay, and checkpoint recovery will enter the same Ymir session primitive for their named world. Today, DTO compatibility methods lower into an isolated Box3D session; they may not run an alternate step or infer retained identity from a body list.

Session identity must be explicit. A process-wide simulator object, zone index, or repeated stable body id is not enough to join two calls to the same world. Aetheria owns run and zone lifetime and creates, retains, and disposes the corresponding embedded Ymir session. Projectile sweep and stationary mine proximity integration can use Ymir's revision-checked retained-session circle-cast and overlap queries. They observe the current stable-id body projection; they do not invent a contact episode or mutate the Box3D world.

Radial gravity and tractor attraction are typed force-generation inputs. They are applied to Box3D before stepping. Pickup collection remains an Aetheria transaction triggered exactly once by a Ymir/Box3D contact fact.

Native Boundary

extern/box3d pins the accepted upstream source. native/Ymir.Box3D owns a small stable C ABI facade. Managed Ymir code binds only to that facade; it does not scatter hundreds of direct P/Invokes across the daemon.

The native facade must remain boring:

• caller-owned blittable buffers;
• explicit version and precision facts;
• no GameCult gameplay policy;
• no JSON state boundary;
• no public exposure of Box3D internal handles;
• first-class RID packaging before production consumers depend on it.

Target Persistence Contract

Canonical deterministic replay starts from the same initial definitions and creation order, then applies the complete command stream under the pinned Box3D build and accepted runtime configuration.

A checkpoint restart is a different promise. Its schema must contain enough typed definitions and state to reconstruct an equivalent Box3D world: stable ids, 3D transforms, linear and angular velocity, body/shape/material/filter definitions, session tuning, and provenance. Box3D does not expose every internal solver cache, so arbitrary mid-world checkpoint restart is tested against named numeric state tolerances rather than claimed as bit-identical continuation. Contact membership, ordering, and exactly-once lifecycle identity are binary contracts, not tolerance checks. Authoritative contact facts resume only after canonical history has been replayed through the checkpoint tick; a checkpoint alone cannot emit gameplay contact facts.

gamecult.ymir.session_checkpoint.replay.v1 implements that promise. It stores the initial definitions, complete typed command journal, logical session generation, command digest, body-generation counter, world verification projection, active contact-episode verification records, and pinned runtime fingerprint. Restore replays into a new Box3D world with outward publication suppressed, then compares the reconstructed boundary exactly before returning a live session. The bounded binary codec rejects incompatible, corrupt, or trailing data and checksums the complete encoded payload. ABI v5 validates the exact pinned native build id, not merely Box3D's public version. Native Box3D identities never enter the checkpoint.

gamecult.ymir.world_state.v2 appends Box3D body type, bullet, field-participation, and collision filter arrays to the v1 layout. The v1 and v0 readers are explicit migration paths; keys are not reassigned. Torque is transient command state and is intentionally absent. Version 2 is a compatibility world snapshot, not a complete retained-session checkpoint: it does not preserve full shape, material, filter, session tuning, provenance, or warm contact state.

Transient forces and torques are commands, not durable body state. Derived mass and inertia are published only when useful for inspection. Old checkpoint versions must migrate explicitly or fail closed; they may not silently decode under a reassigned MessagePack layout.

Cut Line

The managed integrator and circle impulse solver have been deleted from the runtime path. Any uncommitted YmirQueryPrimitives or YmirSpatialIndex work is obsolete and must not be annexed. The retained-session cut continues until Box3D-backed sessions prove:

1. fixed-step body state projection;
2. begin/end/hit contact lifecycle;
3. overlap and shape-cast lowering;
4. continuous collision event timing and same-step Box3D cast witnesses;
5. transient force and torque application;
6. checkpoint reconstruction and replay (implemented; journal compaction and long-running storage remain operational work);
7. Aetheria gravity, tractor, pickup, and payload smokes.

There is no managed fallback after that cut. A native load or compatibility failure fails closed and reports the missing capability.

Required Verification

• Box3D parity tests record released upstream law at the native boundary.
• Ymir differential tests compare public projections with the same Box3D session facts.
• Negative source checks prove custom solver and spatial-index authorities are absent after cutover.
• Aetheria smokes prove gravity, tractor attraction, contact-gated pickup collection/rejection, physical payload hits, and restart continuation through the retained contract. Destruction loot remains Aetheria gameplay state gated by Ymir contact facts where collection occurs.
• Released-client witnesses prove generic Eve clients only observe Ymir and Aetheria provider contracts, never native implementation details.