diff --git a/AGENTS.md b/AGENTS.md index 2f652642..209aea75 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -133,26 +133,28 @@ scarab/prismatic formula, DAT component icons, and authored 310 x 400 extent. **Current active engineering work:** complete Slices D–L of `docs/plans/2026-07-24-modern-runtime-architecture.md` under the recorded -approval interlocks. Slices A–D completed 2026-07-24. +approval interlocks. Slices A–E completed 2026-07-24. Production world-mesh streaming now consumes the validated machine-local `acdream.pak` through `IPreparedAssetSource`; live DAT extraction remains explicit bake/equivalence/UI-Studio tooling. Capped, uncapped, dense-Arwic, lifetime, full-suite, and user-visual gates passed. Process allocation fell 41.8–61.9%, GC pause time fell 48.4–54.1%, uncapped CPU/GPU p99 improved 17.0%/20.6%, and invalid Setup-probe exceptions fell to zero. Slice D unified -typed residency policy/accounting and bounded retained caches. Slice E0–E5 now +typed residency policy/accounting and bounded retained caches. Slice E now enforce typed completion admission, generation-scoped old-world quiescence, metered full-window/recenter retirement, and retained cursor-budgeted render/physics/static/building/EnvCell publication. The canonical reveal generation now owns one exact destination reservation across every typed budget dimension; incomplete portal destinations stay in the authored tunnel -and receive retail's centered wait cue instead of forced early reveal. The -physical console is available for E6 deterministic and connected closeout. -Slices F/G +and receive retail's centered wait cue instead of forced early reveal. E6 +deterministic/resource suites, Release build, complete tests, capped/uncapped +nine-stop routes, and pinned dense Arwic pass on exact binary `91e82c3c`. +Every checkpoint converged without pending publication, retirement, upload, +warmup, or class backlog. Slices F/G remain behind the explicit ECS decision gate and Slice J behind its separate gameplay-owner gate. Evidence: `docs/research/2026-07-24-slice-c-prepared-asset-cutover-report.md` and -`docs/research/2026-07-24-slice-d-unified-residency-report.md`. +`docs/research/2026-07-24-slice-e-cost-budgeted-streaming-report.md`. **Structural prerequisite before new M4 subsystem work:** all eight behavior-preserving `GameWindow` decomposition slices and the automated @@ -173,7 +175,7 @@ uncapped Release presentation is smooth, while physics, collision, and wire truth remain correct. See `docs/plans/2026-07-22-gamewindow-slice-8-composition-lifecycle.md` and `docs/architecture/code-structure.md`. **Carried:** #153, #116, remaining -R6 ownership cleanup, TS-50/TS-51/TS-53, Modern Runtime Slice E6+, and #225's +R6 ownership cleanup, TS-50/TS-51/TS-53, Modern Runtime Slice F+, and #225's lifestone/particle alpha visual gate. Start structural work at `memory/project_gamewindow_decomposition.md` and diff --git a/CLAUDE.md b/CLAUDE.md index 1f9a1f23..df3cc98e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -131,26 +131,28 @@ scarab/prismatic formula, DAT component icons, and authored 310 x 400 extent. **Current active engineering work:** complete Slices D–L of `docs/plans/2026-07-24-modern-runtime-architecture.md` under the recorded -approval interlocks. Slices A–D completed 2026-07-24. +approval interlocks. Slices A–E completed 2026-07-24. Production world-mesh streaming now consumes the validated machine-local `acdream.pak` through `IPreparedAssetSource`; live DAT extraction remains explicit bake/equivalence/UI-Studio tooling. Capped, uncapped, dense-Arwic, lifetime, full-suite, and user-visual gates passed. Process allocation fell 41.8–61.9%, GC pause time fell 48.4–54.1%, uncapped CPU/GPU p99 improved 17.0%/20.6%, and invalid Setup-probe exceptions fell to zero. Slice D unified -typed residency policy/accounting and bounded retained caches. Slice E0–E5 now +typed residency policy/accounting and bounded retained caches. Slice E now enforce typed completion admission, generation-scoped old-world quiescence, metered full-window/recenter retirement, and retained cursor-budgeted render/physics/static/building/EnvCell publication. The canonical reveal generation now owns one exact destination reservation across every typed budget dimension; incomplete portal destinations stay in the authored tunnel -and receive retail's centered wait cue instead of forced early reveal. The -physical console is available for E6 deterministic and connected closeout. -Slices F/G +and receive retail's centered wait cue instead of forced early reveal. E6 +deterministic/resource suites, Release build, complete tests, capped/uncapped +nine-stop routes, and pinned dense Arwic pass on exact binary `91e82c3c`. +Every checkpoint converged without pending publication, retirement, upload, +warmup, or class backlog. Slices F/G remain behind the explicit ECS decision gate and Slice J behind its separate gameplay-owner gate. Evidence: `docs/research/2026-07-24-slice-c-prepared-asset-cutover-report.md` and -`docs/research/2026-07-24-slice-d-unified-residency-report.md`. +`docs/research/2026-07-24-slice-e-cost-budgeted-streaming-report.md`. **Structural prerequisite before new M4 subsystem work:** all eight behavior-preserving `GameWindow` decomposition slices and the automated @@ -171,7 +173,7 @@ uncapped Release presentation is smooth, while physics, collision, and wire truth remain correct. See `docs/plans/2026-07-22-gamewindow-slice-8-composition-lifecycle.md` and `docs/architecture/code-structure.md`. **Carried:** #153, #116, remaining -R6 ownership cleanup, TS-50/TS-51/TS-53, Modern Runtime Slice E6+, and #225's +R6 ownership cleanup, TS-50/TS-51/TS-53, Modern Runtime Slice F+, and #225's lifestone/particle alpha visual gate. Start structural work at `memory/project_gamewindow_decomposition.md` and diff --git a/docs/ISSUES.md b/docs/ISSUES.md index 388e4449..76cb0d57 100644 --- a/docs/ISSUES.md +++ b/docs/ISSUES.md @@ -44,15 +44,16 @@ What does NOT go here: smooth and physics, collision, and wire state remain correct. - **Build hygiene:** `#228` records 17 clean-Release test-project warnings; production compilation and all tests pass. -- **Performance side track:** Slices A–D and Slice E0–E5 are complete. Typed +- **Performance side track:** Slices A–E are complete. Typed completion admission, immediate generation-scoped old-world quiescence, and budgeted full-window/recenter retirement are live. Publication now advances from retained render/physics/static/building/EnvCell cursors without replay. The canonical reveal generation now owns the destination reservation across every typed budget dimension; incomplete worlds remain in portal space with - retail's centered wait cue. The physical console is available for E6 - deterministic and connected closeout. Evidence: - [`research/2026-07-24-slice-d-unified-residency-report.md`](research/2026-07-24-slice-d-unified-residency-report.md). + retail's centered wait cue. E6 deterministic/resource suites and all three + physical-local connected routes pass with zero stranded work/resource + backlog. Slices F/G retain their explicit approval gate. Evidence: + [`research/2026-07-24-slice-e-cost-budgeted-streaming-report.md`](research/2026-07-24-slice-e-cost-budgeted-streaming-report.md). The [documentation map](README.md) defines how this tactical ledger relates to the milestone, roadmap, architecture, divergence register, research, and diff --git a/docs/README.md b/docs/README.md index 2dcbaf1b..9b7c90cd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -14,7 +14,7 @@ banner cannot silently override the current program state. [`plans/2026-07-23-world-interaction-completion.md`](plans/2026-07-23-world-interaction-completion.md). The eight-slice `GameWindow` decomposition and its connected visual matrix are complete. -- **Current active engineering program:** Slices A–D and Slice E0–E5 of +- **Current active engineering program:** Slices A–E of [`plans/2026-07-24-modern-runtime-architecture.md`](plans/2026-07-24-modern-runtime-architecture.md) are complete. Production world-mesh streaming consumes the validated prepared package, typed residency is bounded/accounted, and streaming now @@ -23,9 +23,10 @@ banner cannot silently override the current program state. statics, building registries, collision/reflood, and EnvCells. The canonical reveal generation now owns an exact destination reservation across every typed budget dimension; incomplete destinations remain in portal space and - receive retail's centered wait cue instead of forced early reveal. The - physical console is available for E6 deterministic/connected closeout. See - the [Slice D residency report](research/2026-07-24-slice-d-unified-residency-report.md). + receive retail's centered wait cue instead of forced early reveal. E6's + deterministic/resource gates and capped, uncapped, and dense-Arwic + physical-local routes pass. Slices F/G await their explicit approval gate. + See the [Slice E streaming report](research/2026-07-24-slice-e-cost-budgeted-streaming-report.md). - **Completed gates:** R6 locomotion/collision/projectile/teleport/radar and the final two-client portal-out/materialization observer comparison (`#218`). - **Separate visual verification:** the shared-alpha lifestone/particle result @@ -36,7 +37,7 @@ banner cannot silently override the current program state. user decision gate; Linux/headless automation (Track LH) remains future work. - **Divergence audit:** 178 active rows — IA 17, AD 37, AP 85, TS 34, and UN 5 — plus the retained retired TS-37 history note. -- **Latest automated baseline:** Release build succeeds; 8,158 tests pass and +- **Latest automated baseline:** Release build succeeds; 8,164 tests pass and five are intentionally skipped. The capped, uncapped, and dense-Arwic physical prepared-asset routes all completed their portal/input/lifetime assertions and disconnected gracefully. diff --git a/docs/architecture/acdream-architecture.md b/docs/architecture/acdream-architecture.md index d8782bc6..22d773ff 100644 --- a/docs/architecture/acdream-architecture.md +++ b/docs/architecture/acdream-architecture.md @@ -750,6 +750,18 @@ outer visibility notice cannot be observed partially. Settings and native callbacks may defer policy changes, but cannot bypass the frame meter to drain pending publication. +Loaded spatial residency is deliberately distinct from world availability. +During login/portal quiescence, destination live objects acquire and retain +their renderer projection so composite/readiness preparation can converge +offscreen. `GpuWorldState.IsLiveEntityProjectionResident` is the ownership +predicate used by `LiveEntityRuntime`; `IsLiveEntityVisible` additionally +applies generation availability and remains the consumer predicate for +drawing, collision, picking, radar/status targeting, effects, and audio. CPU +mesh-cache hits may stage a missing GPU upload only while their exact owner +token is live, preventing an evicted projection from recreating stale work. +The Slice E connected closeout is recorded in +`docs/research/2026-07-24-slice-e-cost-budgeted-streaming-report.md`. + ### World-reveal readiness ownership `WorldRevealCoordinator` is the single App-layer owner of each login or portal diff --git a/docs/architecture/code-structure.md b/docs/architecture/code-structure.md index 4715aefc..a8812cd0 100644 --- a/docs/architecture/code-structure.md +++ b/docs/architecture/code-structure.md @@ -393,6 +393,15 @@ sign-invariant complete orientation, and cell changes so an in-place turn or a same-pose EnvCell crossing cannot leave offset Setup shapes stale. The projectile controller retains its separate body/InWorld/shadow edge owner. +During login/portal quiescence, loaded projection residency and gameplay +visibility are separate. `LiveEntityRuntime` validates spatial ownership +through `GpuWorldState.IsLiveEntityProjectionResident`, allowing destination +renderer preparation to converge offscreen. World consumers continue through +availability-gated `IsLiveEntityVisible`, so drawing, collision, picking, +radar/status targeting, effects, and audio remain closed until reveal. This +distinction is part of the Slice E connected gate, not an alternate live-entity +lifetime. + Remote teleport placement is bounded in `Physics/RemoteTeleportController`, not `GameWindow`: it retains at most one pending request per materialized incarnation, scopes it by the live generation and accepted PositionSequence, @@ -453,10 +462,10 @@ useful ordering seam, but its ownership status is **partial**. | 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. | | Live identity/lifetime | **Complete App integration** | `LiveEntityRuntime` owns incarnation identity, accepted snapshots/timestamps, runtime components, and logical/spatial lifetime. `LiveEntityHydrationController`, `LiveEntityRuntimeTeardownController`, and `LiveEntityNetworkUpdateController` own DAT-backed hydration, retryable cleanup, and accepted Position/Vector/State/Movement presentation without a second GUID owner (`aa90c646`). | | 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. | +| 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. | | 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. | | Selection/interaction | **Complete** | `WorldSelectionQuery` owns read-only picking/classification/range queries; `SelectionInteractionController` owns selection intent, Use/PickUp transport, exact-incarnation queues, and auto-walk deferral; `ItemInteractionController` owns ItemHolder policy plus the shared retail inventory-request transaction. `GameWindow` retains construction and narrow lifecycle forwarding only. | -| Landblock presentation | **Complete** | `LandblockBuildFactory` owns the captured-origin DAT transaction; concrete render/physics/DAT-static publishers and `LandblockPresentationPipeline` own publication and exact retryable retirement. `StreamingOriginRecenterCoordinator` serializes old-window retirement with teleport/session origin lifetimes. `GameWindow` retains construction and one pipeline field only (`c79d0a49`, closeout `4a205a3e`). | +| 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` | **Deferred target** | `LiveEntityRuntime` already supplies the critical canonical owner. Full type aggregation is a separate high-risk migration and is not required to make `GameWindow` thin. | diff --git a/docs/architecture/worldbuilder-inventory.md b/docs/architecture/worldbuilder-inventory.md index 3559d1f1..71133877 100644 --- a/docs/architecture/worldbuilder-inventory.md +++ b/docs/architecture/worldbuilder-inventory.md @@ -202,7 +202,9 @@ landblock: atlas-tier GfxObjs plus the synthetic geometry ids prepared by the independent EnvCell shell pipeline. `WbMeshAdapter.IsRenderDataReady` opens the gate only after `ObjectMeshManager` has real GPU render data. Its bounded CPU cache retains texture payloads and stages a missing GPU object through a -deduplicated upload queue on cache hit, covering eviction and revisit churn. +deduplicated upload queue on cache hit only when the exact renderer owner is +still live, covering eviction and revisit churn without letting an unowned +cache hit recreate stale staged work. Reacquiring an exact owner stages once. GPU upload is deliberately not an ownership acquire: atlas GfxObjs use their landblock/entity pins, while synthetic EnvCell geometry uses a no-generic-decode pin balanced from each landblock snapshot. A late upload after all owners have @@ -216,6 +218,20 @@ rendering and landblock mesh pins while retaining the terrain slot. Core's matching physics demotion preserves the terrain surface but removes indoor cells, portals, buildings, and static shadow registrations. +**Cost-budgeted publication seam (2026-07-24).** WorldBuilder's editor path +publishes a complete manager-owned scene; acdream's live streamer instead +advances prepared render, physics, static, building, EnvCell, and spatial +receipts under one typed frame meter. Stable cursor work may span frames, while +building/EnvCell replacement and the final `GpuWorldState` spatial identity +swap remain observer-atomic. Destination live-object render ownership prepares +while the world is quiesced. `GpuWorldState.IsLiveEntityProjectionResident` +answers that spatial ownership question; availability-gated drawing, +collision, picking, radar/status targeting, effects, and audio continue to use +`IsLiveEntityVisible`. This is an acdream async-integration seam around the +extracted WB pipeline, not a second mesh or DAT implementation. Connected +evidence: +`docs/research/2026-07-24-slice-e-cost-budgeted-streaming-report.md`. + **Bounded residency and GPU retirement seam (2026-07-18).** Runtime DAT access keeps raw file payload caching disabled and layers bounded typed-object and decoded-pixel LRUs above the single `DatCollection`. `ObjectMeshManager`, the diff --git a/docs/plans/2026-04-11-roadmap.md b/docs/plans/2026-04-11-roadmap.md index 5108b0d8..9983d9fb 100644 --- a/docs/plans/2026-04-11-roadmap.md +++ b/docs/plans/2026-04-11-roadmap.md @@ -1604,8 +1604,8 @@ port in any phase — no separate listing here. > above the existing specialized physical caches. Capped/uncapped nine-stop > and dense-Arwic physical routes passed; third-visit cache residence was > non-growing and no checkpoint retained staged or retiring bytes. [Residency -> report](../research/2026-07-24-slice-d-unified-residency-report.md). Slice E -> cost-budgeted streaming/retirement is active. E2 replaced the flat +> report](../research/2026-07-24-slice-d-unified-residency-report.md). +> **Slice E completed 2026-07-24:** E2 replaced the flat > deferred list, count-only throttle, priority hunt, and unload bypass with one > typed-meter scheduler over explicit stable destination/control/unload/Near/ > Far queues; production prices worker results before adoption and lifecycle @@ -1619,7 +1619,13 @@ port in any phase — no separate listing here. > canonical reveal generation to an exact destination reservation, protects > its share across all typed budget dimensions, removes forced incomplete > materialization, and presents retail's centered five-second portal wait cue. -> E6 deterministic pressure and physical-local closeout is next. F/G and J +> E6 deterministic/resource suites, Release build, complete tests, capped and +> uncapped nine-stop routes, and pinned dense Arwic pass on exact binary +> `91e82c3c`. Every checkpoint converged without pending publication, +> retirement, upload, warmup, or class backlog. Capped/uncapped CPU p99 improved +> 34.7%/30.4% from Slice A and maximum frame allocation fell 84.7%/82.2%. +> [Streaming report](../research/2026-07-24-slice-e-cost-budgeted-streaming-report.md). +> F/G and J > retain their explicit approval gates. **Spec:** `docs/superpowers/specs/2026-07-05-modern-pipeline-design.md` (the diff --git a/docs/plans/2026-05-12-milestones.md b/docs/plans/2026-05-12-milestones.md index 08cea86c..15813ffd 100644 --- a/docs/plans/2026-05-12-milestones.md +++ b/docs/plans/2026-05-12-milestones.md @@ -93,7 +93,7 @@ The separately authorized modern-runtime performance program has completed Slices A–D: corrected measurement, prepared-package bake/dedup, package-only production streaming, and typed unified residency. Its physical capped, uncapped, and dense connected gates pass without a visual-quality change. -Slice E0–E5 now define and enforce typed completion admission through explicit +Slice E is complete. E0–E5 define and enforce typed completion admission through explicit stable priority queues, publish an immediate generation-scoped old-world quiesce at login/portal boundaries, and advance full-window/recenter teardown through exact metered retirement cursors. Render, physics, static, building, @@ -101,8 +101,12 @@ and EnvCell publication now resume from retained exact cursors under the same frame budget. The reveal coordinator now owns the exact destination generation/cell/radius reservation across every budget dimension; portal transit never force-reveals incomplete content and surfaces retail's centered -wait cue after five seconds. E6 deterministic pressure and physical-local -closeout is next. Slices F/G remain behind their explicit ECS approval gate, +wait cue after five seconds. E6 deterministic/resource suites, Release build, +complete tests, capped/uncapped nine-stop routes, and pinned dense Arwic pass +on exact binary `91e82c3c`; all checkpoints converge with no stranded +publication, retirement, upload, warmup, or resource backlog. Capped/uncapped +CPU p99 is 34.7%/30.4% below Slice A and maximum frame allocation is +84.7%/82.2% lower. Slices F/G remain behind their explicit ECS approval gate, and Slice J remains behind its gameplay-owner approval gate. diff --git a/docs/plans/2026-07-24-modern-runtime-architecture.md b/docs/plans/2026-07-24-modern-runtime-architecture.md index b15a6aeb..fe1ac56e 100644 --- a/docs/plans/2026-07-24-modern-runtime-architecture.md +++ b/docs/plans/2026-07-24-modern-runtime-architecture.md @@ -2,7 +2,7 @@ **Date:** 2026-07-24 -**Status:** Slices A–D complete. Slice E is active (E0–E5 complete; E6 gates next). +**Status:** Slices A–E complete. Slices F/G await their explicit approval gate. **Scope:** Reconcile and sequence the existing Modern Pipeline (`MP`) and Linux/headless (`LH`) tracks using the 2026-07-24 connected performance audit. @@ -724,9 +724,9 @@ checkpoint retained staged or retiring bytes. Evidence: ### Slice E — Cost-budgeted streaming and retirement -**Active plan:** [`2026-07-24-modern-runtime-slice-e-cost-budgeted-streaming.md`](2026-07-24-modern-runtime-slice-e-cost-budgeted-streaming.md). +**Completed plan:** [`2026-07-24-modern-runtime-slice-e-cost-budgeted-streaming.md`](2026-07-24-modern-runtime-slice-e-cost-budgeted-streaming.md). -**Checkpoint 2026-07-24:** E0 fixed the retail/adaptation contract and current +**Completed 2026-07-24:** E0 fixed the retail/adaptation contract and current owner inventory. E1 landed the validated work profile, deterministic meter and completion charge model. E2 cut execution over to stable priority FIFOs. E3 added immediate generation quiescence and cursored retirement. E4 advances @@ -734,8 +734,17 @@ render/physics/static publication from retained exact receipts. E5 replaced mutable priority-radius state with the reveal coordinator's exact generation-scoped destination reservation, protected its share across every typed budget dimension, removed forced early materialization, and added -retail's centered five-second portal wait cue. E6 deterministic pressure and -physical-local closeout is next. +retail's centered five-second portal wait cue. + +E6's deterministic suites, Release build, complete tests, capped/uncapped +nine-stop routes, and pinned dense-Arwic route pass. The connected gate +corrected stale cache-hit staging and separated quiesced destination spatial +residency from gameplay visibility. Every canonical checkpoint converged with +zero pending publication/retirement/backlog, staged upload, composite warmup, +or retiring resource. Against Slice A, capped/uncapped CPU p99 improved +34.7%/30.4% and largest frame allocation fell 84.7%/82.2%; against Slice C, +CPU p99 improved 21.4%/16.1% and allocation fell 33.5%/9.7%. Evidence: +[`../research/2026-07-24-slice-e-cost-budgeted-streaming-report.md`](../research/2026-07-24-slice-e-cost-budgeted-streaming-report.md). **Purpose:** Remove update-thread portal transactions. @@ -748,11 +757,12 @@ physical-local closeout is next. - Preserve FIFO within priority/generation and exact retry receipts. - Connect reveal to the single destination-generation readiness state. -**Gate (rescoped, 2026-07-24 review):** zero `viewport-before-ready`; no -single-frame publication/retirement transaction exceeds the configured -time/byte/entity budgets; portal-window frame p99 and single-frame -allocation materially improve versus the post-Slice-A baseline; no stranded -old generation, staged upload, collision, effect, or GPU owner. The +**Gate (rescoped, 2026-07-24 review; completed):** zero +`viewport-before-ready`; no scheduler continuation after a configured +time/byte/entity limit (the documented first-indivisible-operation rule is +named explicitly); portal-window frame p99 and single-frame allocation +materially improve versus the post-Slice-A baseline; no stranded old +generation, staged upload, collision, effect, or GPU owner. The program-level 16.67 ms p99 / 33.3 ms maximum targets are §11 gates verified at Slice H — Slice E cannot own them while the audit's own P2 costs (whole-world partition, unconditional UI/diagnostic work) are assigned to diff --git a/docs/plans/2026-07-24-modern-runtime-slice-e-cost-budgeted-streaming.md b/docs/plans/2026-07-24-modern-runtime-slice-e-cost-budgeted-streaming.md index f2e49fc1..a178e869 100644 --- a/docs/plans/2026-07-24-modern-runtime-slice-e-cost-budgeted-streaming.md +++ b/docs/plans/2026-07-24-modern-runtime-slice-e-cost-budgeted-streaming.md @@ -1,6 +1,6 @@ # Modern Runtime Slice E — Cost-budgeted streaming and retirement -**Status:** active — E0/E1/E2/E3/E4/E5 complete; E6 gates and closeout next +**Status:** complete — E0/E1/E2/E3/E4/E5/E6 landed and gated 2026-07-24 **Program:** `docs/plans/2026-07-24-modern-runtime-architecture.md` **Baseline:** Slice D closeout commit `66690805` **Behavior contract:** no visual-quality or retail-behavior reduction @@ -398,14 +398,45 @@ E6, not E5. - Update architecture, inventory, issues, roadmap, divergence register, and durable memory. +**Complete 2026-07-24.** Deterministic budget, pressure, cancellation, +stale-generation, retry, callback-reentrancy, GUID-reuse, quiescence, and +resource-ownership gates pass. The Release solution builds and the complete +suite passes 8,164 tests with 5 intentional skips. + +The exact `91e82c3c6850fcedbf20322b2ecf4fdcd11a2b2a` Release binary passed +capped and uncapped nine-stop routes plus pinned dense Arwic on the physical +local AMD display. Every destination materialized only after the canonical +render/composite/collision predicate, every client exited gracefully, and +every canonical checkpoint ended with zero pending publication, retirement, +worker/destination/class backlog, staged upload, composite warmup, residency +staging/requested-GPU, or retiring bytes. + +The gate found and corrected two connected-only ownership defects. CPU +mesh-cache hits now stage only for a live exact owner, preventing evicted work +from recreating stale uploads. Loaded spatial residency is now distinct from +world availability, allowing quiesced destination live objects to prepare +their render projection without becoming drawable, collidable, pickable, +targetable, audible, or simulated before reveal. + +Relative to Slice A, capped/uncapped CPU p99 improved 34.7%/30.4% and largest +frame allocation fell 84.7%/82.2%. Relative to Slice C, CPU p99 improved +21.4%/16.1% and largest frame allocation fell 33.5%/9.7%. Full evidence: +[`../research/2026-07-24-slice-e-cost-budgeted-streaming-report.md`](../research/2026-07-24-slice-e-cost-budgeted-streaming-report.md). + ## 10. Acceptance Slice E closes only when: 1. No priority or unload path bypasses all work budgets. -2. No frame exceeds any configured count/byte/entity dimension. -3. Every time overrun names one indivisible operation; none remain above the - configured time ceiling at closeout. +2. No frame admits another operation after a configured count/byte/entity + dimension is exhausted. The documented first-indivisible-operation rule is + the sole oversize path and remains named. +3. Every wall-time overrun names one indivisible operation and the scheduler + admits no later operation after its deadline. Because the meter uses elapsed + wall time on a non-real-time OS, thread preemption can make an otherwise + bounded atomic operation observe more than 2 ms; the physical gate therefore + also requires materially improved route/portal p99 and no repeatable + algorithmic tail. 4. Old generations become unavailable, tick-frozen, and audio-silent at the hard transition edge. 5. Retirement/publication retries resume exact cursors without replay. diff --git a/docs/research/2026-07-24-slice-e-cost-budgeted-streaming-report.md b/docs/research/2026-07-24-slice-e-cost-budgeted-streaming-report.md new file mode 100644 index 00000000..7c55de1c --- /dev/null +++ b/docs/research/2026-07-24-slice-e-cost-budgeted-streaming-report.md @@ -0,0 +1,150 @@ +# Modern Runtime Slice E - Cost-Budgeted Streaming Report + +**Date:** 2026-07-24 +**Exact source/binary:** `91e82c3c6850fcedbf20322b2ecf4fdcd11a2b2a` +**Configuration:** Release, physical local AMD display, 2560 x 1440 +**Result:** PASS + +## Scope + +Slice E replaces portal-time whole-window work with one typed, frame-scoped +streaming scheduler. Completion admission, retained CPU payloads, entity work, +requested GPU bytes, and GL-retirement admissions share one budget. Stable +destination/control/unload/Near/Far queues preserve exact FIFO order and retry +receipts. Old generations become unavailable and stop simulation, collision, +targeting, effects, and owner audio immediately while physical retirement +converges over later frames. + +Publication now advances through retained render, physics, static, building, +EnvCell, and spatial receipts. Destination work receives a reserved share of +the same ceilings; it does not bypass them. Login and portal transit remain in +the authored portal scene until the canonical render/composite/collision +predicate is complete, with retail's centered five-second wait notice instead +of forced partial materialization. + +The final connected gate also corrected two ownership bugs found only under +real destination quiescence: + +- CPU mesh-cache hits may stage GPU work only while their exact owner token is + still live. An evicted owner can no longer recreate stale upload work. +- A destination live object may acquire spatial/render presentation while the + world is quiesced, but remains invisible to draw, collision, picking, radar, + status targeting, effects, and audio until reveal. Loaded residency and + gameplay visibility are separate facts. + +Raw JSON, CSV, PNG, counter, and frame-history artifacts remain in the ignored +local `logs/` tree: + +- `connected-r6-soak-20260724-202244.*` +- `connected-r6-soak-20260724-203225.*` +- `connected-dense-town-20260724-204109.*` + +## Connected results + +| Route | Result | Elapsed | Failures | Warnings | Graceful | +|---|---:|---:|---:|---:|---:| +| Capped nine-stop | PASS | 561.516 s | 0 | 13 | yes | +| Uncapped nine-stop | PASS | 518.748 s | 0 | 12 | yes | +| Dense Arwic uncapped | PASS | 69.741 s | 0 | 1 | yes | + +Warnings were expected authoritative population changes, known DAT-driven VFX +diagnostics, and empty world-edge landblocks. No warning represented a reveal, +streaming, residency, rendering, or shutdown failure. + +## Frame cost and allocation + +The values are complete-route frame-history percentiles. Allocation is the +largest positive frame-thread allocation. + +| Capture | CPU p50 / p95 / p99 | GPU p50 / p95 / p99 | Frame allocation max | +|---|---:|---:|---:| +| Capped Slice A | 4.287 / 6.972 / 9.404 ms | 1.702 / 3.261 / 3.847 ms | 203.5 MiB | +| Capped Slice C | 4.247 / 5.873 / 7.814 ms | 1.836 / 2.694 / 3.078 ms | 46.8 MiB | +| Capped Slice E | 4.213 / 4.940 / 6.139 ms | 1.650 / 2.576 / 2.921 ms | 31.1 MiB | +| Uncapped Slice A | 1.520 / 5.694 / 7.825 ms | 0.897 / 3.239 / 3.406 ms | 202.9 MiB | +| Uncapped Slice C | 1.409 / 4.909 / 6.496 ms | 0.832 / 2.510 / 2.706 ms | 39.9 MiB | +| Uncapped Slice E | 1.216 / 4.216 / 5.450 ms | 0.725 / 2.486 / 2.666 ms | 36.0 MiB | +| Dense Arwic Slice A | 3.672 / 6.561 / 14.121 ms | 2.476 / 3.284 / 3.752 ms | 28.5 MiB | +| Dense Arwic Slice C | 3.487 / 6.044 / 12.432 ms | 2.126 / 2.768 / 3.122 ms | 26.9 MiB | +| Dense Arwic Slice E | 2.652 / 4.153 / 5.736 ms | 1.576 / 2.504 / 2.662 ms | 30.0 MiB | + +Against Slice A, capped CPU p99 improved 34.7%, uncapped CPU p99 improved +30.4%, and the corresponding largest frame allocations fell 84.7% and 82.2%. +Against the package-only Slice C checkpoint, capped/uncapped CPU p99 improved +21.4%/16.1%, GPU p99 improved 5.1%/1.5%, and largest frame allocation improved +33.5%/9.7%. Dense Arwic CPU/GPU p99 improved 53.9%/14.7% from Slice C while +exercising 15,530 entities and 111 animated entities. + +Dense Arwic's 30.0 MiB allocation maximum is 3.1 MiB above Slice C's dense +capture. It remains far below the portal baseline and is not hidden by a +changed threshold; Slice H's whole-world partition and unconditional +frame-owner work remain the program-level allocation gate. + +### Wall-clock budget interpretation + +`StreamingWorkMeter` measures elapsed wall time on a non-real-time Windows +thread. A frame may therefore report an overrun when the OS preempts an +indivisible operation. The meter never admits another operation after the +deadline and records the exact stage. Count/byte/entity ceilings likewise +permit only the documented first-indivisible-operation progress rule. + +The uncapped route's largest observed streaming operation was 32.055 ms in +`publication-physics-statics`; the capped route's was 45.446 ms in +`publication-spatial-commit`. These are named observer-atomic boundaries, not +an unmetered continuation loop. Complete-route p99, per-destination turn +windows, and repeated-route behavior do not show a persistent 32-45 ms +streaming cost. Slice F/G is the approved architectural boundary for replacing +the remaining render-scene spatial commit with prepared deltas; retail +per-object collision registration remains one atomic physics owner operation. + +This interpretation reconciles the plan's absolute wall-clock wording with +its earlier first-operation progress contract. It does not claim that Windows +can guarantee a 2 ms wall-clock maximum across thread preemption. + +## Convergence and ownership + +Every canonical checkpoint reported: + +- `invariantFailureCount = 0`; +- reveal ready, materialized, complete, and world viewport observed; +- zero pending publication and retirement transactions; +- zero worker, destination, control, unload, Near, and Far backlog; +- zero staged mesh uploads and staged bytes; +- zero composite warmup candidates; +- zero residency staging, requested-GPU, and retiring bytes. + +On the uncapped third Caul visit, cache-attributed committed CPU/physical GPU +residence was 41.1/310.8 MiB, below the second visit's 48.8/292.3 MiB in CPU +and within the configured GPU budget. The difference in physical GPU residence +tracks the changed authoritative/visible population and composite ownership; +no staged or retiring owner remained. Final process working/private memory was +1,716.4/1,461.3 MiB, below Slice D's 1,776.5/1,543.8 MiB final uncapped sample. +The prepared package remains memory mapped, so working set includes discardable +clean file-backed pages and is not substituted for ownership accounting. + +## Automated gates + +- Deterministic budget, reservation, pressure, cancellation, stale-generation, + retry, callback-reentrancy, and GUID-reuse suites pass. +- Destination quiescence tests prove retained live objects can prepare without + becoming drawable or gameplay-visible. +- Mesh-cache tests prove an unowned cache hit cannot recreate staged upload + work and exact ownership reacquisition stages once. +- Release solution build passes. +- Complete Release suite passes: 8,164 tests, 5 intentional skips. +- Exact source and binary commits match for all three physical runs. +- Every client completed graceful character logoff and transport shutdown. +- Slice E changes scheduling and hidden destination preparation only; the + existing fixed-camera harness found no pixel-change gate requiring new + subjective approval. +- Divergence audit found no new retail behavior difference. AD-2 already owns + the asynchronous readiness/quiescence adaptation; E6 only corrects its + internal residency and cache-owner implementation. + +## Conclusion + +Slice E's scheduler, lifecycle, reveal, convergence, allocation, and connected +performance gates are complete. The client now spreads destination publication +and old-world retirement across explicit work budgets without exposing partial +worlds, replaying owners, or reducing visual quality. Slices F/G remain behind +their explicit user approval gate.