docs(render): close unified residency slice
This commit is contained in:
Erik
parent
1853a57c12
commit
66690805c5
8 changed files with 192 additions and 5 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
119
docs/research/2026-07-24-slice-d-unified-residency-report.md
Normal file
119
docs/research/2026-07-24-slice-d-unified-residency-report.md
Normal file
|
|
@ -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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue