acdream/docs/research/2026-07-24-audit-review-remediation-handoff.md

2026-07-24 — Runtime-audit adversarial review + remediation: HANDOFF

For: the next agent/session picking up this work. State when written: all remediation commits landed on local main (7b456b49 tip), full solution test suite green (Debug + Release build, dotnet test AcDream.slnx exit 0), user visual pass PASSED 2026-07-24 for both render-affecting changes. Remotes deliberately not pushed.

---

1. What happened today

An independent adversarial review (43 verification agents against pinned commit e627d9a4) audited both docs/research/2026-07-24-runtime-performance-audit.md and docs/plans/2026-07-24-modern-runtime-architecture.md. Verdict: APPROVE WITH CHANGES for both — the audit's code-level diagnosis was almost entirely correct (12/12 spot-checked file:line citations accurate), but its measurement provenance was not, and the plan inherited gates its tooling could not measure plus one governance hole. The user then approved executing the five headline recommendations, which are now done.

2. Review findings that must not be re-litigated (all verified at file:line)

Corrections to the audit (now recorded as audit §13 errata — read it before citing the audit's §1/§2/§4 numbers):

1. The capture ran forced-uncapped (ACDREAM_UNCAPPED_RENDER=1 set unconditionally by the soak script) with undisclosed ACDREAM_DUMP_MOVE_TRUTH=1; "normal capped presentation" was false — the 32 FPS ceiling was purely the RDP display path. Unresolved wrinkle: the CPU trace's 6.44% FramePacingController.CompleteFrame should be a no-op under those flags (launcher provenance is muddy).
2. The headline 203.6 MiB "single-frame allocation" is frame-thread-only (GC.GetAllocatedBytesForCurrentThread); worker-side MeshExtractor decode structurally cannot be in it. The frame spike belongs to main-thread publication/retirement (Slice E owns it); the pak (Slices B/C) owns the process-wide 40.8 MB/s rate, Gen-2 pressure, and 256 ms GC pauses. Win attribution must respect that split.
3. 65% LOH fragmentation (524 MB of 807 MB) sat unanalyzed in the audit's own JSON — the best committed explanation of the committed-vs-live gap.
4. Exception figures: only the focused-trace 1,587 (1,335 AOOR + 252 socket) are verifiable; the plan's old "4,520 + 1,168" had no committed derivation (plan §1 row corrected).
5. gen0=99 < gen1=105 is legal (.NET 10 meter reports per-generation EXCLUSIVE counts; ≈242 total GCs); "38 Gen-2" stands.
6. GiB conversions were MiB/1000 (true peaks: 1.62 GiB WS / 2.22 GiB private); committed-heap peak was 1,242–1,298 MiB, not 830.6.

Pivotal confirmations (the audit was right): the streaming budget-bypass is real (MaxCompletionsPerFrame=4 count budget; unloads + teleport priority-ring apply uncapped; BeginFullWindowRetirement retires ~600 landblocks in one frame); LandblockRetirementCoordinator.RunForEachEntity is unmetered; LandblockStaticPresentationPublisher rebuilds dicts/sets/sorts per publication (plus a third dictionary + per-attempt re-sort the audit missed); ResolveActivation probes every static id as Setup with a bare catch and no negative cache anywhere; InteriorEntityPartition.Partition walks all resident entities per frame with its AABB parameter unused (nuance: far-tier blocks are entity-stripped, so the walk is bounded by near-tier + live); GpuFrameTimer gpu_ms is boundary-to-boundary and invalid under a cap; the viewport-before-ready barrier is real but observational-only today (never gates reveal).

Cache reality (correction to the audit's framing): four bounded LRU tiers already front the mesh/texture path (GPU render-data 1 GiB/50 obj; CPU mesh 128 MiB/100; decoded-texture 64 MiB/128; DAT typed-object 64 MiB/256 ×4) — revisits rebuild because they are UNDERSIZED vs the route's working set (~599 textures), not because caching is absent. Real fence-gated eviction exists for atlases/composites/arena — the route never pushed the ceilings. Slice D = unify accounting + retune, not rebuild.

Lock contention (4,614) is unattributed — no stacks were captured. Leading candidates: _datLock (whole-landblock build vs render-thread CreateObject hydration — a known 2026-06-23 campaign; portal windows are exactly its worst case) and ObjectMeshManager._pendingRequests, not only the DAT typed-object lock the audit named.

3. What was executed (all on local main, in order)

Commit	Content
38e14c6a	docs: audit errata §13 + plan amendments — §0 governance (F/G user gate, side-track session discipline, freeze-exception scope for H-c/J, evidence corrections, baseline prerequisite blocking Slice C), Slice A/C/D/E/F/G/H/I/J/K contracts, §11 gate corrections, §12 adjudication protocol, §14 order incl. Slice I
c2cb83d1	EnvCellRenderer prepare gate — the dead NeedsPrepare wired into a real dirty gate (landblock changes, filter content, trim, new ObjectMeshManager.RenderDataAvailabilityVersion, camera = 1 mm ABSOLUTE eye epsilon + rows-1–3 relative 1e-5; a matrix-relative epsilon would mask sub-meter motion at AC's ~5e4 coords). Pool-cursor discipline verified safe. USER-ACCEPTED (visual pass 2026-07-24).
cf253304	net: receive-thread no longer dies on stray SocketException — SIO_UDP_CONNRESET suppression, per-iteration catch/continue+log, setsockopt hoist; deterministic loop-resilience tests
a4b1214e	dead code: ParticleBatcher/ParticleEmitterRenderer/ActiveParticleEmitter chain deleted (+ orphaned EmbeddedResourceReader + wb_particle shaders); production particle path untouched. USER-ACCEPTED (visual pass).
60bc3139	MeshExtractor: CellStruct clip-map clone guard (was unconditional), solid-color texture cache (clone-protect flag wired), redundant double .ToList() dropped (Portal-wins ordering untouched)
1e9031e7	audio: DatSoundCache 32 MiB LRU + negative set; OpenAL buffer 48 MiB budget with attachment-safe eviction; 19 tests
bfc5e473	ISSUES #236–#244 — deferred P2 findings (see §5)
7b456b49	measurement tooling: ACDREAM_FRAME_HISTORY=<path> per-frame CSV export (zero frame-thread I/O, written at Dispose); checkpoint JSON gains LOH size/fragmentation, process-total-allocated, and hit/miss/evict counters for the CPU-mesh/decoded-texture/DAT caches; soak script gains -Uncapped switch (default is now CAPPED), 26 s dwell fix, per-run env-disclosure.json

Memory updated: feedback_agent_worktree_base (new — see §6), project_mp_track_findings (2026-07-24 update block; EnvCell rebuild gate was its parked MP-Alloc item, now landed + accepted).

4. Next actions, in order (the incoming agent's decision space)

1. Mint the baselines (measurement, no code; plan §0.5 blocks Slice C on these): one capped nine-stop soak (new script default) + one -Uncapped soak; the AUTHORITATIVE uncapped-local run needs the user at the physical display (not RDP). ACE was up on 127.0.0.1:9000. Command: .\tools\run-connected-r6-soak.ps1 -Repository (Get-Location).Path -SkipBuild [-Uncapped] with ACDREAM_TEST_USER/PASS set; artifacts land in the automation dir + commit the JSON/CSV like the 2026-07-24 set. Set ACDREAM_FRAME_HISTORY for the per-frame export.
2. Slice A remainder (small coding): pinned dense-town scene baseline (pick Arwic or Fort Tethana, pin camera in a route file), screenshot-diff tool + match rule, contention-stack capture (dotnet-trace Contention keyword) on the route, a percentile script over the per-frame CSV, the committed reference-config block.
3. Then Slice B (EnvCell geomId dedup + full pak bake) in dedicated MP side-track sessions — first real plan slice.
4. Main line always wins: M4's six-slice world-interaction program is the active milestone critical path; MP work is side-track-only (plan §0.2).
5. Fillers (one commit each): #236 UiText cache and #241 partition frustum cull are the best value; #237 Transition pooling stays gated on Slice I lifetime tests.
6. Do NOT start Slices F/G without the user's recorded go-ahead (plan §0.1 — they resume the deferred 2026-07-05 MP3/ECS decision; the prior "GPU-bound ~200fps" evidence is invalidated by the GpuFrameTimer artifact, so the question stays open until the corrected uncapped-local profile exists post-Slice-E).

5. Deferred, filed, and known-not-done

• ISSUES #236–#244: UiText per-frame re-wrap; Transition per-resolve allocation graph; EquippedChildRenderController double-tick + ToArray snapshots; inbound per-packet allocation chain; RetailAnimationLoader unbounded cache; partition landblock frustum cull; publisher third dictionary/per-attempt re-sort; _boundsCache bound; SequencerFactory unguarded Setup probe + [dat-miss] under-lock logging.
• Remotes: local main is 30+ commits ahead of origin and github (both at 20e2998a). Deliberately not pushed — prior convention says local main is the truth; push with git push origin main github main (or per-remote) when the user wants the stack published.
• No baseline soak was run yet (held to avoid colliding with the user's visual-pass session). The tooling is validated by contract tests
  • a clean PS1 parse only.
• The audit's raw artifacts remain uncommitted (by design); several §4 numbers stay reproducible-not-reviewed until the Slice A recapture.

6. Gotchas for the incoming agent

• Worktree-agent base skew: Agent-tool worktrees in this repo were created from the REMOTE tip (20e2998a), ~90 commits behind local main. Always have agents report their worktree HEAD, run git diff --name-only <agentBase> <target> -- <touched files> before cherry-picking, and re-run the full suite on the target tree. (Memory: feedback_agent_worktree_base.)
• The four agent worktrees from this session were unregistered from git and their branches deleted after cherry-picking. Three orphaned DIRECTORIES (.claude/worktrees/agent-a5cccad7a993e2db7, agent-a4124a11d80d1805b, agent-a5670375d0717edf5) remained file-locked at handoff time — plain disk litter, delete whenever the locks clear. vigorous-joliot-f0c3ad was detached from main so the primary tree could check it out — it still exists, detached at e627d9a4.
• The soak script's route gating GREPS move-truth OUT lines — ACDREAM_DUMP_MOVE_TRUTH must stay enabled for soak runs (now disclosed via env-disclosure.json, not hidden).
• Plan §14's "landed post-review" notes mark work done today — do not redo it when executing slices.

7. Pointers

• Audit + errata: docs/research/2026-07-24-runtime-performance-audit.md (§13)
• Amended plan: docs/plans/2026-07-24-modern-runtime-architecture.md (§0 first)
• Issues: docs/ISSUES.md #236–#244 (+ current queue block)
• Memory: claude-memory/project_mp_track_findings.md (2026-07-24 update), claude-memory/feedback_agent_worktree_base.md, claude-memory/project_render_pipeline_digest.md (unchanged, still the render SSOT)
• Full review structure (A–G: verdict, findings, benchmark/architecture assessments, revised execution order, acceptance matrix) was delivered in-session 2026-07-24; its actionable content is fully folded into the errata, the plan amendments, the issues above, and this handoff.