docs(runtime): record reveal ownership gate

This commit is contained in:
Erik 2026-07-26 17:26:50 +02:00
parent acb845d812
commit 38b3773cb9
9 changed files with 191 additions and 25 deletions

View file

@ -238,7 +238,10 @@ src/
RuntimeOrdinaryPhysicsUpdater.cs -> presentation-free object simulation
RuntimeProjectile.cs -> canonical projectile component/prediction owner
RuntimeProjectilePhysicsUpdater.cs -> presentation-free projectile simulation
-> J3J5 complete; J6 world/portal/environment handshake active
World/
RuntimeWorldEnvironmentState.cs -> canonical calendar/time/weather owner
RuntimeWorldTransitState.cs -> canonical reveal generation/readiness owner
-> J3J5 and J6.1J6.2 complete; J6.3 transit handshake active
-> may reference Core, Core.Net, Content, and Plugin.Abstractions only
-> must never reference App, UI, Silk.NET, OpenAL, Arch, or ImGui
@ -281,8 +284,8 @@ src/
Streaming/
StreamingController.cs -> done
GpuWorldState.cs -> done
WorldRevealCoordinator.cs -> shared login/portal lifetime owner
WorldRevealReadinessBarrier.cs -> canonical destination predicate
WorldRevealCoordinator.cs -> graphical host/reveal projection adapter
WorldRevealReadinessBarrier.cs -> graphical destination-readiness source
Input/
PlayerMovementController.cs -> active movement driver
Plugins/
@ -865,12 +868,21 @@ The Slice E connected closeout is recorded in
### World-reveal readiness ownership
`WorldRevealCoordinator` is the single App-layer owner of each login or portal
reveal lifetime. It composes the canonical `WorldRevealReadinessBarrier` with
generation-scoped lifecycle observation and the streaming destination
reservation plus a generation-scoped render-resource profile, so begin,
preparation, readiness, materialization, viewport release, protocol completion,
cancellation, and reserved capacity cannot be wired independently. While the
`RuntimeWorldTransitState` is the single presentation-independent owner of
each login or portal reveal generation. It owns the exact destination, typed
atomic readiness latch, materialization/simulation edge, viewport observation,
completion, cancellation, retail wait cue, and portal materialization count.
Stale generations, wrong destinations, invalid readiness shapes, reordered
edges, and post-cancel acknowledgements cannot mutate the active generation.
Once readiness is accepted it remains latched; later sampled graphical
readiness may fall as resources transition without closing the accepted edge.
`WorldRevealCoordinator` is the graphical host adapter. It evaluates App's
`WorldRevealReadinessBarrier`, acknowledges that typed result to Runtime, and
owns only the streaming destination reservation, render-resource profile,
selection/audio projection edges, and viewport release. App's former lifecycle
telemetry/generation owner is deleted and
`WorldGenerationAvailabilityState` is a read-only Runtime projection. While the
normal world viewport is withheld, mesh and composite upload owners may admit
more small destination items per frame, but retain the ordinary 8 MiB byte,
array, buffer, and mipmap ceilings. The exact profile ends at the retail

View file

@ -469,17 +469,17 @@ useful ordering seam, but its ownership status is **partial**.
|---|---|---|
| Startup options | **Complete** | `RuntimeOptions` owns startup configuration (`eda936dc`). Remaining direct environment reads are legacy runtime diagnostics, not startup configuration. |
| Network session | **Complete Runtime ownership** | `RuntimeLiveSessionController` owns the sole `WorldSession` generation and resolve/create/Connect/selection/EnterWorld/Tick/stop/reconnect/disposal transaction. Runtime route owners preserve exact inbound/outbound ordering and retryable teardown. App supplies immutable options, graphical/domain callbacks, and one borrowed inertable UI command projection—no mirrored session or reset plan (`75930787`). |
| World environment | **Complete ownership** | `WorldEnvironmentController` solely owns WorldTime, the loaded DAT sky, current day group, Weather, server synchronization, AdminEnvirons bridging, and debug time/weather cycles. `GameWindow` keeps ABI-compatible readonly aliases to the same clock/weather instances and composes one render source plus the two live-session callbacks. TS-54/TS-55 register the remaining centered UI sound and full fog/ambient/radar behavior gaps. |
| World environment | **J6.1 complete Runtime ownership** | `RuntimeWorldEnvironmentState` owns the instance-scoped Dereth calendar, synchronized clock, weather progression/state, selected day group, AdminEnvirons state, and typed debug overrides. App converts immutable DAT sky definitions once and projects the borrowed Runtime snapshot into rendering; no process-global Region origin or second App clock/weather owner remains (`902076c0`). TS-54/TS-55 register the remaining centered UI sound and full fog/ambient/radar behavior gaps. |
| Live identity/lifetime | **J3 complete** | `RuntimeEntityObjectLifetime` owns the sole `RuntimeEntityDirectory`, live `ClientObjectTable`, direct views, and ordered entity/object stream. The directory owns canonical GUID/incarnation/local-ID identity, accepted snapshots/timestamps, parent state, operation versions, and tombstones. `LiveEntityProjectionStore` owns App graphical sidecars by exact `RuntimeEntityKey`; hydration, presentation components, `GpuWorldState` residence/visibility, and retryable teardown preserve that key without another authority. Exact receipts precede fallible callbacks, re-entrant commits drain synchronously in sequence, and stable reset/disposal must converge the complete ledger to zero (`f46ddb5c`, `420e5eea`, `e937cc36`, `5ef8b537`, `ce3ac310`, `119b7c11`). |
| Inbound/object-frame order | **Complete App orchestration** | `UpdateFrameOrchestrator` owns the complete typed host phase graph; `RetailInboundEventDispatcher`, `RetailLiveFrameCoordinator`, `LiveObjectFrameController`, `LiveSpatialPresentationReconciler`, streaming/input/teleport/player-mode/camera owners preserve the accepted order. `GameWindow.OnUpdate` is one profiler-scoped handoff (`e91f3102`). |
| World reveal | **Complete** | `WorldRevealCoordinator` owns login/portal readiness, generation quiescence, and the exact streaming destination reservation. Login auto-entry and portal completion close only their active generation; stale completion cannot clear its replacement. Delayed portals retain the authored tunnel and centered retail wait notice rather than force-revealing incomplete content. Quiesced destination projections may become spatially resident for renderer preparation while all availability-gated gameplay consumers stay closed. |
| World reveal | **J6.2 complete Runtime ownership** | `RuntimeWorldTransitState` owns the sole monotonic login/portal reveal generation, exact destination, typed atomic readiness latch, materialization/simulation edge, viewport observation, completion, cancellation, retail wait cue, and portal count. `WorldRevealCoordinator` is the graphical host adapter over App readiness/reservations; `WorldGenerationAvailabilityState` borrows Runtime truth and owns no mutable generation. Delayed portals retain the authored tunnel and centered retail wait notice rather than force-revealing incomplete content (`a6860d55`, `acb845d8`). |
| Retained gameplay UI | **Mostly complete feature ownership** | `RetailUiRuntime` and focused panel/controllers own layout and behavior. `GameWindow.OnLoad` still performs substantial service composition, which is allowed until the final composition cleanup. |
| Action/combat/magic/movement | **J5 complete** | Runtime `RuntimeActionState` owns the exact selection, temporary target mode, interaction transactions, combat attack/target/mode, and spell-cast intent children. Interaction owns use/appraisal/pickup identity, ordered FIFO, and exact post-arrival token while borrowing J4's sole busy gate. `RuntimeLocalPlayerMovementState` owns the exact local controller, construction seam, autorun latch, typed view, and outbound MTS/jump/AP cadence. Retained bars, physical input, world/content queries, transport, lighting, toasts, drag/drop, effects, and animation remain App adapters/presentation. One combined Runtime ledger spans entity/object, gameplay, physics, remote, and projectile ownership (`b298f99f`, `f5f7b417`, `20df9d15`, `aa3f4a60`, `cdee7a4b`). |
| Physics/remote simulation | **J5.5 complete** | `RuntimePhysicsState` owns one per-session engine, production cache/cell graph, transition scratch, shadow registry, typed collision admissions, canonical bodies/hosts/remotes, keyed ordinary/remote worksets, simulation, and cell commits. App streaming supplies immutable prepared collision; animation/shape adapters supply graphical inputs and project committed snapshots only (`7e6033d0`). |
| Projectile simulation | **J5.6 complete** | `RuntimeEntityRecord`/`RuntimePhysicsState` own the canonical projectile component, exact-key workset, prediction/correction state, unchanged retail quantum/integration/sweep/collision loop, and cell commits. App resolves immutable Setup/DAT shape input and projects committed render, shadow, and effect-pose results only (`2aee3356`). |
| Landblock presentation | **Complete** | `LandblockBuildFactory` owns the captured-origin DAT transaction; concrete render/physics/DAT-static publishers and `LandblockPresentationPipeline` own typed-meter publication and exact retryable retirement. `StreamingController` owns stable destination/control/unload/Near/Far queues and destination reservation. CPU mesh-cache restaging requires an exact live owner. `StreamingOriginRecenterCoordinator` serializes old-window retirement with teleport/session origin lifetimes. `GameWindow` retains construction and one pipeline field only (`c79d0a49`, closeout `4a205a3e`; Slice E closeout `91e82c3c`). |
| Render-frame orchestration | **Complete** | `RenderFrameOrchestrator` owns the GPU-flight, resource, world/PView/shared-alpha, private-presentation, diagnostics, screenshot, and recovery graph. `GameWindow.OnRender` takes one logical window-size snapshot and performs one immutable handoff (`9d7df1bf`). |
| Unified `GameEntity` | **Slice J active at J6** | Canonical identity, retained-object lifetime, direct views, ordered entity/object deltas, J4 gameplay state, and the complete J5 action/combat/magic/movement/physics/remote/projectile simulation graph share failure-safe Runtime owners while exact graphical sidecars stay in App. J5 closeout proves Runtime-only parity and one terminal ownership ledger. J6 now separates authoritative world/portal/environment state from presentation readiness before J7 composes one `GameRuntime` root. |
| Unified `GameEntity` | **Slice J active at J6.3** | Canonical identity, retained-object lifetime, direct views, ordered entity/object deltas, J4 gameplay state, and the complete J5 action/combat/magic/movement/physics/remote/projectile simulation graph share failure-safe Runtime owners while exact graphical sidecars stay in App. J5 closeout proves Runtime-only parity and one terminal ownership ledger. J6.1J6.2 moved world environment and reveal-generation truth; J6.3 now moves F751/Position destination correlation before J7 composes one `GameRuntime` root. |
### 4.3 Revised extraction sequence

View file

@ -1,6 +1,6 @@
# acdream — strategic roadmap
**Status:** Living document. Updated 2026-07-26. **M3 landed; M4 is active.** M3's retail casting/UI, R6 locomotion/collision/projectile/teleport/radar rebaseline, deterministic fresh-login/portal world lifecycle, and final two-client portal observer flow are user-gated. All eight slices of the behavior-preserving ownership campaign in [`docs/architecture/code-structure.md`](../architecture/code-structure.md), their automated closeout, and the user's connected visual matrix are complete. Modern Runtime J3 canonical entity/object lifetime and J4 gameplay-state ownership are closed at `89e6b207`; J5.1 canonical selection/combat/target-mode ownership is closed at `b298f99f`, J5.2 interaction transactions at `f5f7b417`, J5.3 combat/magic intent at `20df9d15`, J5.4 local movement/outbound cadence at `aa3f4a60`, J5.5 per-session physics/remote simulation at `7e6033d0`, J5.6 projectile simulation at `2aee3356`, and J5.7 combined simulation closeout at `cdee7a4b`. J6.1 world-environment ownership is closed at `902076c0`; J6.2 canonical reveal generation and typed destination readiness is active. Issue #225's lifestone/particle alpha comparison remains a separate rendering visual gate.
**Status:** Living document. Updated 2026-07-26. **M3 landed; M4 is active.** M3's retail casting/UI, R6 locomotion/collision/projectile/teleport/radar rebaseline, deterministic fresh-login/portal world lifecycle, and final two-client portal observer flow are user-gated. All eight slices of the behavior-preserving ownership campaign in [`docs/architecture/code-structure.md`](../architecture/code-structure.md), their automated closeout, and the user's connected visual matrix are complete. Modern Runtime J3 canonical entity/object lifetime and J4 gameplay-state ownership are closed at `89e6b207`; J5.1 canonical selection/combat/target-mode ownership is closed at `b298f99f`, J5.2 interaction transactions at `f5f7b417`, J5.3 combat/magic intent at `20df9d15`, J5.4 local movement/outbound cadence at `aa3f4a60`, J5.5 per-session physics/remote simulation at `7e6033d0`, J5.6 projectile simulation at `2aee3356`, and J5.7 combined simulation closeout at `cdee7a4b`. J6.1 world-environment ownership is closed at `902076c0`; J6.2 canonical reveal generation and typed destination readiness is closed at `a6860d55` plus `acb845d8`; J6.3 teleport packet/destination correlation is active. Issue #225's lifestone/particle alpha comparison remains a separate rendering visual gate.
**Purpose:** One source of truth for where the project is and where it's going. Every observed defect or missing feature has a named phase that owns it; when something looks wrong in-game, look here to find the phase that'll address it. Implementation details live in per-phase specs under `docs/superpowers/specs/`, not in this file.
---
@ -1781,7 +1781,13 @@ port in any phase — no separate listing here.
> synchronized world clock, weather, selected day group, and AdminEnvirons
> state; its 332 Runtime tests, 3,718 App tests / 3 skips, 8,611-test / 5-skip
> complete Release suite, and exact-binary lifecycle/reconnect route pass.
> J6.2 canonical reveal generation and typed destination readiness is active.
> J6.2 completed at `a6860d55` plus `acb845d8`: Runtime owns the sole
> reveal generation, destination/readiness latch, materialization,
> simulation-availability, viewport, completion, cancellation, and wait-cue
> state. Its 349 Runtime tests, 3,716 App tests / 3 skips, 8,626-test / 5-skip
> complete Release suite, and exact-binary lifecycle/reconnect route pass with
> zero reveal invariants. J6.3 teleport packet/destination correlation is
> active.
> The historical exact cutover
> rollback remains
> `git revert ef1d263337997bb030eadb7b8e71d73dc659907a`. Slice H is complete:

View file

@ -256,7 +256,12 @@ residency is `0/0/0` at every stable checkpoint and teardown converges. Slice I
AdminEnvirons state; App projects immutable DAT-backed sky presentation.
Its 332 Runtime tests, 3,718 App tests / 3 skips, 8,611 complete Release
tests / 5 skips, and exact-binary lifecycle/reconnect route pass. J6.2
canonical reveal generation and typed destination readiness is active under
completed at `a6860d55` plus `acb845d8`: Runtime owns the sole reveal
generation, destination/readiness latch, materialization, availability,
viewport, completion, cancellation, and wait-cue state; App's lifecycle
mirror is deleted. Its 349 Runtime tests, 3,716 App tests / 3 skips, 8,626
complete Release tests / 5 skips, and exact-binary lifecycle/reconnect route
pass with zero reveal invariants. J6.3 transit correlation is active under
[`2026-07-25-modern-runtime-slice-j.md`](2026-07-25-modern-runtime-slice-j.md).
Slice-I closeout evidence is
[`../research/2026-07-25-slice-i7-closeout.md`](../research/2026-07-25-slice-i7-closeout.md).

View file

@ -354,11 +354,13 @@ graphical feel gates remain unchanged.
### J6 — world, portal, environment, and projection handshake
**J6.0J6.1 complete; J6.2 active 2026-07-26.** The instance-scoped Runtime
environment owner landed at `902076c0`; exact day-group, Release, full-suite,
and connected lifecycle/reconnect gates pass. Detailed owner inventory, retail
ordering, host-acknowledgement contract, execution ledger, adversarial matrix,
and current evidence:
**J6.0J6.2 complete; J6.3 active 2026-07-26.** The instance-scoped Runtime
environment owner landed at `902076c0`. The canonical reveal generation and
typed readiness owner landed at `a6860d55` plus `acb845d8`; App's duplicate
lifecycle owner is deleted and the exact connected lifecycle/reconnect gate
passes with zero reveal invariants. Detailed owner inventory, retail ordering,
host-acknowledgement contract, execution ledger, adversarial matrix, and
current evidence:
[`2026-07-26-modern-runtime-slice-j6.md`](2026-07-26-modern-runtime-slice-j6.md).
- Move authoritative teleport/session cell identity, world clock, weather

View file

@ -1,6 +1,6 @@
# Modern runtime Slice J6 — world, transit, and host handshake
**Status:** J6.0J6.1 COMPLETE; J6.2 ACTIVE
**Status:** J6.0J6.2 COMPLETE; J6.3 ACTIVE
**Parent:** `2026-07-25-modern-runtime-slice-j.md`, J6
**Authorization:** the user approved Slices FL, including gameplay-owner
moves, on 2026-07-24
@ -221,6 +221,9 @@ and exited gracefully with code zero. Evidence:
### J6.2 — canonical reveal generation and typed readiness
**Complete 2026-07-26 at `a6860d55` plus connected correction
`acb845d8`.**
- Add `RuntimeWorldTransitState`, immutable readiness acknowledgement, and
direct `IRuntimePortalView`.
- Move lifecycle telemetry and generation state from App to Runtime.
@ -235,6 +238,24 @@ and exited gracefully with code zero. Evidence:
Gate: login, portal, supersession, stale acknowledgement, callback failure,
session reset, and exact two-release-edge fixtures pass.
Result: Runtime owns the sole monotonic reveal generation, destination,
typed readiness latch, materialization/simulation edge, viewport observation,
completion, cancellation, wait cue, and portal materialization count. App's
former lifecycle owner is deleted; `WorldRevealCoordinator` is a graphical
host adapter and `WorldGenerationAvailabilityState` is a read-only Runtime
projection. The first connected run correctly exposed that post-acceptance
render-readiness samples may regress while the accepted atomic edge must
remain latched; `acb845d8` ignores those later samples without mutating
Runtime truth or reporting false invariant failures.
Runtime tests pass 349/349, App tests pass 3,716/3 skips, and the complete
Release suite passes 8,626/5 skips. Exact-binary report
`logs/connected-world-gate-20260726-171724/report.json` records six capped
checkpoints and one uncapped fresh-process reconnect, graceful code-zero exits,
zero failures, zero reveal invariant failures, and only the expected
world-edge warning. Evidence:
[`../research/2026-07-26-slice-j6-2-reveal-ownership.md`](../research/2026-07-26-slice-j6-2-reveal-ownership.md).
### J6.3 — canonical F751/Position transit and placement handshake
- Move `TeleportTransitCoordinator` state into the Runtime transit owner.
@ -324,6 +345,13 @@ J6.1 exact rollback:
git revert 902076c0a42079596a8a273e9be402776cabf4b0
```
J6.2 exact rollback, newest first:
```text
git revert acb845d812574206da1693fb379fec8a6f175fcb
git revert a6860d5563ae845a2cbb916abacf2b4aee515cdb
```
Documentation-only research/plan commits are not behavior rollback points.
No workaround, timer, forced-ready path, duplicated owner, or alternate
headless behavior is permitted.

View file

@ -0,0 +1,93 @@
# Slice J6.2 — canonical reveal-generation ownership
**Date:** 2026-07-26
**Production commits:** `a6860d5563ae845a2cbb916abacf2b4aee515cdb`,
`acb845d812574206da1693fb379fec8a6f175fcb`
**Exact rollback, newest first:**
```text
git revert acb845d812574206da1693fb379fec8a6f175fcb
git revert a6860d5563ae845a2cbb916abacf2b4aee515cdb
```
## Outcome
`AcDream.Runtime.World.RuntimeWorldTransitState` now owns one canonical
login/portal reveal lifetime:
- monotonically increasing generation and exact destination cell;
- typed destination-readiness acknowledgement and atomic accepted latch;
- materialization and world-simulation availability;
- normal-world viewport observation;
- completion, cancellation, and session reset;
- the retail five-second wait cue;
- portal materialization count and invariant diagnostics.
`WorldRevealLifecycleTelemetry` and its App snapshot were deleted. App's
`WorldRevealCoordinator` now reports graphical readiness and performs
streaming/render-resource, selection, audio, and viewport side effects over
the same Runtime owner. `WorldGenerationAvailabilityState` is a read-only
projection and `CurrentGameRuntimeViewAdapter` borrows the Runtime portal view
directly instead of reconstructing it.
Runtime rejects stale generations, wrong destination cells, invalid
indoor/radius shapes, early materialization, early viewport reveal, premature
completion, and post-cancel work. Accepted readiness is sticky: graphical
readiness is a sampled host fact and may legitimately fall after Runtime has
accepted the atomic destination edge.
## Retail ordering
- `SmartBox::TeleportPlayer @ 0x00453910`
- `SmartBox::UseTime @ 0x00455410`
- `gmSmartBoxUI::EndTeleportAnimation @ 0x004D65A0`
The Runtime transition preserves retail's ordering: destination
materialization resumes world simulation while portal space still covers the
world; the normal viewport is observed later; completion follows the authored
WorldFadeIn/LoginComplete tail. No timeout or forced reveal was introduced.
## Automated evidence
- Runtime: 349 passed.
- App: 3,716 passed / 3 skipped.
- Complete solution: 8,626 passed / 5 skipped.
- Release build: zero errors; 17 pre-existing test-project warnings tracked by
issue #228.
- Ownership/source guards: one production Runtime transit construction, no App
lifecycle owner, no reconstructed portal view.
- Adversarial fixtures: wrong/stale generation, wrong destination, malformed
readiness, reordered edges, duplicate acknowledgement, post-ready sampling,
supersession, cancellation, session reset, generation reuse, two-instance
isolation, unhydratable destination, and throwing diagnostics.
One cold parallel full-suite run tripped the existing
`PortalProjectionTests.ProjectToClipLease_ReusesPooledWorkWithoutResultArrays`
allocation threshold by 2,008 bytes. The test passed immediately in isolation
and the complete suite then passed unchanged.
## Connected evidence
Accepted report:
`logs/connected-world-gate-20260726-171724/report.json`
The report records exact source and embedded binary commit
`acb845d812574206da1693fb379fec8a6f175fcb`.
- Capped process: 243.942 seconds, six checkpoints, graceful code-zero exit.
- Uncapped fresh-process reconnect: 61.625 seconds, one checkpoint, graceful
code-zero exit.
- Route: fresh login, Aerlinthe, Rynthid world edge, Facility Hub dungeon,
Holtburg, Aerlinthe revisit, then fresh-process reconnect.
- Failures: zero.
- Reveal invariant failures: zero.
- Expected warning: 25 instrumented world-edge landblock misses.
The earlier report
`logs/connected-world-gate-20260726-171020/report.json` is deliberately
rejected. It proved that graphical readiness may fall after accepted
materialization and exposed an incorrect diagnostic classification in
`a6860d55`; `acb845d8` keeps the accepted latch but treats later sampled
readiness as non-authoritative.
No new retail divergence was introduced.