docs(runtime): close J3.3 and hand off J3.4

Record exact projection-store ownership, automated and connected evidence, rollback chain, and the executor-ready canonical object-table plan. Reconcile milestones, roadmap, architecture, divergence pointers, AGENTS/CLAUDE, and durable handoff state.

Co-authored-by: Codex <codex@openai.com>
This commit is contained in:
Erik 2026-07-25 22:29:34 +02:00
parent e937cc36df
commit d9bf4c4960
15 changed files with 757 additions and 114 deletions

View file

@ -209,7 +209,12 @@ src/
ordered deltas, clock, generation + teardown
Session/ -> J2 canonical session lifetime, ordered
inbound routing + retryable teardown
-> J3 identity, properties, and object-table extraction active
Entities/
RuntimeEntityDirectory.cs -> sole GUID/incarnation/local-ID authority
RuntimeEntityRecord.cs -> presentation-free accepted entity state
InboundPhysicsStateController.cs -> retail timestamp/snapshot authority
ParentAttachmentState.cs -> generation-exact parent relations
-> J3.1-J3.3 complete; J3.4 canonical object-table ownership next
-> may reference Core, Core.Net, Content, and Plugin.Abstractions only
-> must never reference App, UI, Silk.NET, OpenAL, Arch, or ImGui
@ -230,7 +235,8 @@ src/
RemoteTeleportHook.cs -> ordered retail teleport teardown seam
RemoteTeleportPlacement.cs -> collision-seated SetPosition transition commit
World/
LiveEntityRuntime.cs -> canonical identity/state/body/projectile/spatial ownership
LiveEntityRuntime.cs -> exact-key App projection/lifecycle host
LiveEntityProjectionStore.cs -> materialized sidecars by RuntimeEntityKey
RetailInboundEventDispatcher.cs -> update-thread packet/frame FIFO barrier
LiveEntityPresentationController.cs -> Hidden/NoDraw/effect/collision presentation
LiveEntityTeardown.cs -> failure-isolated multi-owner lifecycle drain
@ -447,26 +453,38 @@ Ownership by phase:
## GameEntity: The Unified Entity (target refactor)
`LiveEntityRuntime` is now the shipped bridge to this target. It owns one
`LiveEntityRecord` per accepted server-object incarnation, ServerGuid-to-local-id
translation, accepted snapshots/timestamp gates, the canonical `PhysicsBody`,
animation/remote-motion/projectile components, parent-event state,
effect-profile defaults, and exact logical
teardown. Live `PhysicsDesc` effect fields replace Setup defaults on that same
record; rebucketing never recreates them. `GpuWorldState`
owns spatial buckets only: register/rebucket/unregister are separate operations,
logical teardown removes the exact `WorldEntity` incarnation rather than every
projection sharing its server GUID, and per-GUID/session mutation epochs prevent
a callback from resurrecting an outer CreateObject after delete/reset. Per-GUID
epoch tombstones remain until session clear, so delete-then-create cannot repeat
an outer operation's epoch (the ABA problem). Resource registration is an atomic
boundary, superseded cleanup failures surface at the runtime boundary, and
visibility observers are failure-isolated without interrupting canonical commits.
Landblock reloads reuse the same `WorldEntity` without replaying renderer or
script creation. Its canonical materialized view remains stable across pending
landblocks, while a separate visible-only view feeds radar, picking, status, and
targeting. Raw server PhysicsState and the final state produced by retail's
ordered Lighting/NoDraw/Hidden side effects are stored separately.
The shipped bridge is now split at the Runtime/App boundary.
`AcDream.Runtime.Entities.RuntimeEntityDirectory` owns the only current
server-GUID/incarnation map, Runtime local-ID allocation/reverse lookup,
accepted snapshots and timestamp gates, parent state, session/operation
versions, and exact tombstones. `RuntimeEntityRecord` is presentation-free.
`LiveEntityRuntime` is the App projection/lifecycle host.
`RegisterLiveEntity` first creates or refreshes canonical Runtime state without
an App record. `MaterializeLiveEntity` claims the Runtime local ID and creates
one graphical `LiveEntityRecord` sidecar in `LiveEntityProjectionStore`, keyed
by exact `RuntimeEntityKey` (local ID plus `INSTANCE_TS`). The sidecar owns the
App animation, remote-motion, projectile, hydration, and effect presentation
state. `RuntimeEntityRecord` deliberately still carries the canonical
`PhysicsBody`/physics-host facts until their coherent J5 move.
Live `PhysicsDesc` effect fields replace Setup defaults on that same exact
sidecar; rebucketing never recreates it.
`GpuWorldState` owns spatial buckets only and retains the exact projection key
through loaded/pending movement, landblock retirement/reload, origin recenter,
quiescence, and visibility transition delivery. Register, rebucket, withdraw,
and unregister remain separate operations. Logical teardown removes the exact
`WorldEntity` incarnation rather than every projection sharing its server GUID.
Runtime per-GUID/session operation versions prevent a callback from
resurrecting an outer CreateObject after delete/reset, and exact tombstones
prevent ABA reuse. Resource registration is an atomic boundary, superseded
cleanup failures surface at the runtime boundary, and visibility observers are
failure-isolated without interrupting canonical commits. Landblock reloads
reuse the same `WorldEntity` without replaying renderer or script creation.
Focused exact-key materialized queries remain stable across pending landblocks;
focused visible queries feed radar, picking, status, and targeting. Raw server
PhysicsState and the final state produced by retail's ordered
Lighting/NoDraw/Hidden side effects are stored separately.
When retail's 25-second leave-visibility deadline expires, active ownership
still ends completely. The ACE adapter retains only the accepted
`EntitySpawn` in `DormantLiveEntityStore`, because ACE can keep that GUID in
@ -494,10 +512,11 @@ does not depend on Content or a database implementation.
Runtime effect delivery is owned by App-layer `EntityEffectController`. It
retains pre-materialization F754/F755 packets in one mixed FIFO per server GUID,
resolves the canonical local ID through `LiveEntityRuntime` only after
renderer/resources/profile are ready, and resolves typed/default/part-default
hooks through the live owner's current `EntityEffectProfile`. It does not own a
second GUID map. The same profile publishes Setup/static or network/live
asks Runtime for the current canonical incarnation, then resolves the exact
App projection only after renderer/resources/profile are ready. It resolves
typed/default/part-default hooks through that projection's current
`EntityEffectProfile`; it does not own a second GUID map. The same profile
publishes Setup/static or network/live
SoundTable ownership at readiness and on every same-generation PhysicsDesc
replacement, including present-zero clearing. Core `PhysicsScriptRunner` mirrors retail's one
serial FIFO per owner: duplicate plays append, owners progress independently,
@ -920,7 +939,8 @@ Current movement/collision ownership:
- **B.3** is shipped MVP history: first collision resolver foundation.
- **L.1/R6** own animation/motion parity and the complete retail object-frame
update order over canonical `LiveEntityRuntime` records.
update order over canonical Runtime records plus exact-key App projection
sidecars.
- **L.2** owns the remaining movement and collision conformance:
`docs/plans/2026-04-29-movement-collision-conformance.md`.
- **G.3 is shipped**: dungeon streaming, portal-space presentation, collision,