From 66690805c5f8c053cf8f048daf9fd352c3485899 Mon Sep 17 00:00:00 2001 From: Erik Date: Fri, 24 Jul 2026 17:06:06 +0200 Subject: [PATCH] docs(render): close unified residency slice --- docs/ISSUES.md | 7 +- docs/architecture/acdream-architecture.md | 13 ++ docs/architecture/worldbuilder-inventory.md | 14 +++ docs/plans/2026-04-11-roadmap.md | 9 ++ docs/plans/2026-05-12-milestones.md | 8 ++ .../2026-07-24-modern-runtime-architecture.md | 12 +- ...odern-runtime-slice-d-unified-residency.md | 15 ++- ...-07-24-slice-d-unified-residency-report.md | 119 ++++++++++++++++++ 8 files changed, 192 insertions(+), 5 deletions(-) create mode 100644 docs/research/2026-07-24-slice-d-unified-residency-report.md diff --git a/docs/ISSUES.md b/docs/ISSUES.md index 0b987b1e..d3bb4199 100644 --- a/docs/ISSUES.md +++ b/docs/ISSUES.md @@ -44,9 +44,10 @@ 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:** prepared-content Slices A–C are complete; - `#244` is closed and Slice D unified residency/accounting is next. Evidence: - [`research/2026-07-24-slice-c-prepared-asset-cutover-report.md`](research/2026-07-24-slice-c-prepared-asset-cutover-report.md). +- **Performance side track:** prepared-content Slices A–C and unified-residency + Slice D are complete. Slice E cost-budgeted streaming/retirement is next. + Evidence: + [`research/2026-07-24-slice-d-unified-residency-report.md`](research/2026-07-24-slice-d-unified-residency-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/architecture/acdream-architecture.md b/docs/architecture/acdream-architecture.md index 62f4d7a4..d66a46d0 100644 --- a/docs/architecture/acdream-architecture.md +++ b/docs/architecture/acdream-architecture.md @@ -512,6 +512,19 @@ the waiting attachment graph transitively, so A→B→C recovers B before C in t same parent-first pass. Recovery is edge-triggered by object/appearance/pose publication; permanent missing DAT or holding parts are never polled per frame. +Runtime content residence has one typed policy and diagnostic ledger without +centralizing physical storage. `ResidencyManager` owns generation-safe logical +asset identity, owner tokens, leases, immutable budgets, and aggregate +accounting. Specialized render/content owners continue to own their mesh +ranges, texture arrays, staging payloads, decoded animations/audio, and +retained shared-alpha scratch. The manager never sees a GL name: policy runs as +a single writer during update/resource maintenance, while logical eviction and +fence-delayed physical release remain render-thread owner operations. Prepared +package address space is reported separately from committed CPU bytes, and +allocator capacity is not double-counted as live GPU content. Slice D's +pressure and connected evidence is +`docs/research/2026-07-24-slice-d-unified-residency-report.md`. + The remaining aggregation is primarily `_playerController`'s player-specific movement plus the separate `WorldEntity`/animation/physics component types. Those should become ONE class: diff --git a/docs/architecture/worldbuilder-inventory.md b/docs/architecture/worldbuilder-inventory.md index 31150a1b..3559d1f1 100644 --- a/docs/architecture/worldbuilder-inventory.md +++ b/docs/architecture/worldbuilder-inventory.md @@ -230,6 +230,20 @@ no longer reference them. This lifetime machinery is acdream-owned integration around the extracted WB mesh pipeline; it does not add a second DAT decoder or a reduced-distance rendering path. +**Unified residency policy seam (2026-07-24).** The extracted WB caches remain +the physical owners of mesh, arena, atlas, and texture resources. +`AcDream.App.Rendering.Residency.ResidencyManager` adds an acdream-owned typed +policy/diagnostic layer over them: generation-safe asset handles, independent +owner tokens and leases, immutable startup budgets, aggregate accounting, and +bounded trim requests. It never stores or deletes a GL name. Existing owners +perform logical eviction and fence-delayed physical release on the render +thread. The same ledger observes the prepared-package mapping, prepared/staged +CPU mesh data, decoded animation/audio data, and retained shared-alpha scratch +without double-counting the package's clean memory-mapped pages as committed +heap. Deterministic pressure tests exceed every configured ceiling and prove +zero-charge teardown. Connected evidence: +`docs/research/2026-07-24-slice-d-unified-residency-report.md`. + **Workflow:** Before re-implementing any AC-specific rendering or dat-handling algorithm, **check this inventory first**. If we already extracted it (🟢 sections), it's in `src/AcDream.App/Rendering/Wb/` — use our copy. If WB has diff --git a/docs/plans/2026-04-11-roadmap.md b/docs/plans/2026-04-11-roadmap.md index 36f59b76..f8104a60 100644 --- a/docs/plans/2026-04-11-roadmap.md +++ b/docs/plans/2026-04-11-roadmap.md @@ -1598,6 +1598,15 @@ port in any phase — no separate listing here. > process allocation fell 41.8–61.9%, GC pause time fell 48.4–54.1%, and > invalid typed-Setup exceptions fell to zero. [Cutover > report](../research/2026-07-24-slice-c-prepared-asset-cutover-report.md). +> **Slice D completed 2026-07-24:** typed asset/owner generations, leases, +> immutable budget profiles, exact aggregate diagnostics, bounded +> animation/audio/alpha-scratch owners, and forced-pressure coverage now sit +> 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. F/G and J retain their explicit +> approval gates. **Spec:** `docs/superpowers/specs/2026-07-05-modern-pipeline-design.md` (the umbrella design — read it first). **Goal:** smoothness first (no frame over diff --git a/docs/plans/2026-05-12-milestones.md b/docs/plans/2026-05-12-milestones.md index f3f6be28..ff74caa0 100644 --- a/docs/plans/2026-05-12-milestones.md +++ b/docs/plans/2026-05-12-milestones.md @@ -89,6 +89,14 @@ transactions. This is deliberately using the extracted interaction owners and canonical shared main-panel host before quest/emote/character-creation bodies broaden the feature surface. +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 E cost-budgets portal publication and retirement next. Slices F/G remain +behind their explicit ECS approval gate, and Slice J remains behind its +gameplay-owner approval gate. + Slice 1's 18-cell favorite-spell overflow bar is user-accepted. Slice 2's status hand selected-object availability and existing Use/AutoWield/use-on-target command routing passed their connected gate. diff --git a/docs/plans/2026-07-24-modern-runtime-architecture.md b/docs/plans/2026-07-24-modern-runtime-architecture.md index 27419235..08ed3239 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–C complete. Slice D is next and not yet started. +**Status:** Slices A–D complete. Slice E is active. **Scope:** Reconcile and sequence the existing Modern Pipeline (`MP`) and Linux/headless (`LH`) tracks using the 2026-07-24 connected performance audit. @@ -687,6 +687,16 @@ Release suite, and the user's visual gate passed. Process allocation fell **Gate:** same-location third-visit residence plateaus; no stale-generation release; no missing textures; no resource growth after repeated portal loops. +**Completed 2026-07-24:** typed asset/owner generations, leases, immutable +budget profiles, specialized-owner adapters, exact aggregate accounting, +bounded animation/audio/alpha-scratch policies, forced-pressure coverage, and +fence-aware retirement diagnostics are live. The capped/uncapped physical +nine-stop routes and dense Arwic passed with graceful shutdown. The third Caul +checkpoint reduced cache-attributed CPU/GPU residence from the second visit, +animations plateaued at 55 entries, scratch stayed below budget, and no +checkpoint retained staged or retiring bytes. Evidence: +[`../research/2026-07-24-slice-d-unified-residency-report.md`](../research/2026-07-24-slice-d-unified-residency-report.md). + **Amendment (2026-07-24 review).** Two corrections to this slice's scope: - **Do not rebuild what exists.** Fence-gated, budgeted eviction already diff --git a/docs/plans/2026-07-24-modern-runtime-slice-d-unified-residency.md b/docs/plans/2026-07-24-modern-runtime-slice-d-unified-residency.md index ab9eb10c..a0827280 100644 --- a/docs/plans/2026-07-24-modern-runtime-slice-d-unified-residency.md +++ b/docs/plans/2026-07-24-modern-runtime-slice-d-unified-residency.md @@ -1,6 +1,6 @@ # Modern Runtime Slice D — Typed Asset Handles and Unified Residency -**Status:** active — D1 through D4 complete +**Status:** complete — D1 through D5 passed 2026-07-24 **Program:** `docs/plans/2026-07-24-modern-runtime-architecture.md` **Baseline:** Slice C closeout commit `a564c4b7` **Behavior contract:** no visual-quality or retail-behavior change @@ -271,6 +271,17 @@ LRU pressure, and alpha-scratch convergence. Release build and the complete - Preserve fixed-camera screenshots and obtain the user's visual gate if the connected route changes any visible frame. +**Complete 2026-07-24.** The exact D4 source/binary commit `1853a57c` passed +the capped and uncapped physical-local nine-stop routes and pinned dense Arwic, +with zero failures and graceful transport shutdown in all three processes. +Cache-attributed residence was non-monotonic: the third Caul checkpoint fell +from the second visit's 50.3/355.0 MiB committed-CPU/physical-GPU residence to +38.5/335.1 MiB. Parsed animations stopped at 55 entries, alpha scratch stayed +below 16 MiB, and staged/retiring bytes were zero at every checkpoint. The +harness's fixed-camera captures passed without a visible-frame change. Exact +methodology and measurements: +[`../research/2026-07-24-slice-d-unified-residency-report.md`](../research/2026-07-24-slice-d-unified-residency-report.md). + ## 9. Acceptance Slice D closes only when: @@ -285,3 +296,5 @@ Slice D closes only when: 6. The architecture, roadmap, issues, inventory, and durable memory agree with the implementation. 7. Connected screenshots retain Slice C's visual output. + +All seven conditions passed 2026-07-24. diff --git a/docs/research/2026-07-24-slice-d-unified-residency-report.md b/docs/research/2026-07-24-slice-d-unified-residency-report.md new file mode 100644 index 00000000..ed89a529 --- /dev/null +++ b/docs/research/2026-07-24-slice-d-unified-residency-report.md @@ -0,0 +1,119 @@ +# Modern Runtime Slice D — Unified Residency Report + +**Date:** 2026-07-24 +**Exact source/binary:** `1853a57c12ee16f8d1d2c41cca60851a4bd89de6` +**Configuration:** Release, physical local AMD display, 2560 × 1440 +**Result:** PASS + +## Scope + +Slice D did not replace the renderer's specialized physical caches or alter +visual quality. It placed their limits and exact occupancy behind one typed +policy/diagnostic ledger, added generation-safe logical identity and leases, +bounded the previously unbounded animation and retained-alpha-scratch owners, +and made decoded audio part of the same accounting model. + +The final gate exercised the exact D4 binary through: + +- capped Caul → Sawato → Rynthid → Aerlinthe → Sawato → Holtburg → Caul → + Sawato → Caul; +- the same nine-stop route uncapped; +- pinned dense Arwic uncapped; +- fixed-camera screenshots at every canonical checkpoint; +- graceful character logoff and transport disconnect. + +Raw JSON, CSV, PNG, trace, and frame-history artifacts remain in the ignored +local `logs/` tree: + +- `connected-r6-soak-20260724-164203.*` +- `connected-r6-soak-20260724-165143.*` +- `connected-dense-town-20260724-170034.*` + +## Connected results + +| Route | Result | Elapsed | Failures | Warnings | Graceful | +|---|---:|---:|---:|---:|---:| +| Capped nine-stop | PASS | 514.308 s | 0 | 9 | yes | +| Uncapped nine-stop | PASS | 508.793 s | 0 | 11 | yes | +| Dense Arwic uncapped | PASS | 67.570 s | 0 | 1 | yes | + +Warnings were expected authoritative population changes, known VFX +diagnostics, and empty world-edge landblocks. No warning represented a +residency, reveal-readiness, rendering, or shutdown failure. + +### Frame cost + +The values below are turn-window p95 CPU/GPU milliseconds. Lower means more +frame time remains for other work. + +| Destination | Capped CPU / GPU | Uncapped CPU / GPU | +|---|---:|---:| +| Caul first | 8.0 / 3.6 | 7.5 / 3.2 | +| Sawato first | 4.6 / 1.7 | 2.1 / 1.3 | +| Rynthid | 4.6 / 1.8 | 2.4 / 1.5 | +| Aerlinthe | 4.6 / 2.2 | 2.1 / 1.4 | +| Sawato revisit | 4.6 / 1.8 | 1.6 / 0.9 | +| Holtburg | 4.7 / 2.1 | 3.7 / 2.1 | +| Caul return | 5.4 / 3.1 | 6.0 / 3.2 | +| Sawato plateau | 4.6 / 1.3 | 1.7 / 1.0 | +| Caul plateau | 8.4 / 3.4 | 7.0 / 3.3 | + +Pinned dense Arwic, with 15,530 entities and 111 animations, measured +5.4 ms CPU p95 and 3.0 ms GPU p95 while turning. These measurements confirm +that the connected route is normally CPU-limited rather than GPU-limited. +They are evidence for the explicit Slice F/G approval decision, not permission +to begin that deferred ECS work. + +## Residency plateau + +The capped run's aggregate ledger is summarized below. CPU excludes the +prepared package's clean memory-mapped address space; GPU is cache-attributed +physical residence, not every framebuffer/shader/UI allocation tracked by the +independent process-wide GPU tracker. + +| Checkpoint | Committed CPU | Physical GPU | Animations | Alpha scratch | Retiring | +|---|---:|---:|---:|---:|---:| +| Caul first | 36.8 MiB | 185.1 MiB | 26 | 8.10 MiB | 0 | +| Sawato first | 39.4 MiB | 247.1 MiB | 33 | 1.87 MiB | 0 | +| Rynthid | 23.3 MiB | 277.2 MiB | 39 | 2.62 MiB | 0 | +| Aerlinthe | 39.6 MiB | 277.3 MiB | 43 | 3.97 MiB | 0 | +| Sawato revisit | 30.3 MiB | 277.3 MiB | 43 | 3.97 MiB | 0 | +| Holtburg | 39.4 MiB | 347.0 MiB | 50 | 4.70 MiB | 0 | +| Caul return | 50.3 MiB | 355.0 MiB | 51 | 8.54 MiB | 0 | +| Sawato plateau | 36.1 MiB | 363.0 MiB | 55 | 2.28 MiB | 0 | +| Caul plateau | 38.5 MiB | 335.1 MiB | 55 | 8.53 MiB | 0 | + +The third Caul visit used less cache-attributed CPU and GPU residence than the +second. Parsed-animation residence stopped at 55 entries, retained alpha +scratch remained below its 16 MiB aggregate budget, staged and retiring bytes +were zero at every canonical checkpoint, and all reported owners stayed within +their configured limits. + +Process working set and private bytes are intentionally not substituted for +these ownership facts. The 27.53 GiB prepared package is memory mapped; Windows +counts touched clean file-backed pages in working set even though they are +discardable and are not committed cache ownership. The uncapped run ended at +1,776.5 MiB working set and 1,543.8 MiB private bytes after warming all nine +destinations. Slice E still owns the remaining portal publication/retirement +allocation and frame-transaction work. + +## Automated gates + +- Typed transition, cancellation, failure, owner-reuse, and stale-generation + conformance tests pass. +- Every bounded domain has deterministic forced-pressure coverage. +- Physical cache tests prove eviction and fence-delayed release. +- All-domain teardown converges to zero reported charge. +- Release build passes. +- Complete Release suite passes: 8,111 tests, 5 intentional skips. +- Connected fixed-camera screenshots passed the existing harness comparisons; + Slice D introduced no visible-frame change requiring a new subjective gate. + +## Conclusion + +Slice D's policy and acceptance gates are complete. Runtime cache memory is now +finite, attributable, generation-safe, and pressure-tested without reducing +view distance, particle distance, texture quality, or retail presentation. +Slice E is the next approved step: spread portal publication and retirement +over explicit per-frame cost budgets while keeping retired objects immediately +inactive and destination reveal correctness exact.