acdream/docs/research/2026-09-01-overhaul/s5-consumers-material-closeout-packet.md

Campaign OVERHAUL v2 — S5 consumers, material, and closeout packet

Status: S5-c1 IMPLEMENTED 2026-09-04; sequential review pending. Branch: claude/campaign-w-retail-frame-walk. Gate: G4 remains unpassed. Nothing merges to main before G4.

This packet decomposes plan S5 into bounded chunks. The lead writes each contract, a Sonnet implementer changes only that contract, the lead verifies every retail claim against the named pseudo-C and the paired executable/PDB, and the sequential review lenses run before landing. A chunk that needs a third fix round stops and is written up. Every surviving deviation is entered or corrected in the divergence register in the same implementation commit.

1. Current boundary after S4

S4-c3b is landed and the lead G3 matrix is a provisional PASS; owner inspection and the owner-only G3 rows remain. S5 must not reopen the green walk, portal depth, or two-FIFO alpha ports without new evidence.

The landscape half is already present and exact:

• WalkLandscape.CheckBlocks / LandCellCheck port LScape::draw_check_blocks @0x00505F80 and LScape::landcell_check @0x005050A0;
• WalkVisibilityMath owns the ported get_clip_height / block_check math;
• WalkFrameDriver.VisitedLandscapeCellIds is populated by the same one walk that emits the retail-ordered terrain/object stream.

S5-c1 therefore changes the consumers and deletes the competing fallback. It does not rewrite the landscape calculation.

2. Retail facts for S5-c1 (lead-verified 2026-09-04)

The executable is C:\Users\erikn\Downloads\acclient.exe. Its CodeView record is GUID {9E847E2F-777C-4BD9-886C-22256BB87F32}, age 1, matching refs/acclient.pdb.

2.1 ShouldDrawParticles is distance AND the cell virtual

Named pseudo-C at CPhysicsObj::ShouldDrawParticles @0x0050FE60 reads:

if examination: true
if CYpt > degrade_distance: false
if cell == null: false
if cell->IsInView() == 0: false
true

The paired bytes are the same: fld [ecx+0x24], fcomp [esp+4], the x87 test ah,0x41 gate, null-check of [ecx+0x90], then the virtual call through vtable slot +0x68. ParticleEmitter::UpdateParticles @0x0051D180 calls that function at 0x0051D1A1; false enters the SetNoDraw(1) / degraded_out=1 arm, while true clears that state and updates/emits particles.

Preserve the existing x87-compatible comparison, including inclusive equality, unordered admission, raw negative/zero/NaN/infinity authored distances, and the deliberate AP-116 range multiplier (Retail=1, default Extended=2).

2.2 outdoor and indoor cells have different IsInView semantics

• CLandCell::IsInView @0x00532CB0 returns the 32-bit field at +0x104. The paired body is exactly mov eax,[ecx+0x104]; ret. Landscape drawing stamps that field, so particle update consumes the previous completed render frame's landscape answer.
• CEnvCell::IsInView is the PDB-vtable slot at 0x007C8D00, pointing to the ICF-folded body 0x005269F0. The paired body is exactly mov eax,1; ret. Thus an indoor cell with a non-null owner is always PARTIALLY_INSIDE for the update-time check; its particle drawing remains separately controlled by the cell walk.

AC cell identity already has a production-pinned discriminator: low = cellId & 0xFFFF; outdoor land cells have 0 < low < 0x0100, EnvCells have low >= 0x0100, and zero is no cell.

2.3 point lights do not consume the camera walk

Retail collects point lights from the DBObj-load/flush-bounded resident CEnvCell::visible_cell_table, not from the current camera portal flood. Current LightManager.BuildPointLightSnapshot(playerWorldPos) likewise uses the resident registry. RuntimeWorldFrameEnvironmentPreparation's ObserveDrawableCells / ClearDrawableCells methods are now no-ops, while AP-85 still describes the deleted last-frame filter. The methods and the stale claim are tombstones, not behavior.

2.4 the null-root terrain reconstruction is not a retail answer

In-world retail has a viewer-cell root. acdream's null-root path is the AD-21 streaming-gap/debug safety draw. TerrainModernRenderer.CollectVisibleCells manufactures 64 land-cell ids per retained landblock from camera-frustum AABBs and publishes them through TerrainVisibleCellIds. That is the only remaining AP-117 reconstruction. A safety draw with no walk product must publish no outdoor IsInView answer; it must not invent one.

3. S5-c1 contract — typed IsInView consumers and fallback deletion

3.1 C1 — publish the landscape half explicitly

Extend the borrowed RetailPViewFrameResult with the exact landscape land-cell set from WalkFrameDriver.VisitedLandscapeCellIds. Keep DrawableCells for EnvCell shell preparation and keep the existing union VisibleCells only for diagnostics that compare the two products. Do not re-filter, re-walk, sort, or derive the landscape set from projection/entity ids.

Rename the particle handoff to make the type visible in the API, for example MarkVisibleLandscapeCells. It accepts only outdoor land-cell ids and copies them into the controller's building frame. Passing zero or an EnvCell id is a contract violation, not something to silently reinterpret.

The completed frame remains the sole retained owner. AbortFrame preserves the prior completed product, CompleteFrame publishes the new product, and Reset removes both generations. The update thread continues to call Apply before the next render, preserving retail's previous-frame timing.

3.2 C2 — evaluate the correct virtual by cell family

Change ParticleSystem.ApplyRetailView so a world-policy emitter is eligible only when all of the following are true:

hasCompletedView
ownerCellId != 0
(owner is EnvCell OR exact completed landscape set contains ownerCellId)
retail x87-compatible distance predicate

EnvCell means low >= 0x0100; landscape means 0 < low < 0x0100. Examination and dedicated-pass policies keep their existing bypass. This is an update/degrade correction only: do not alter emitter-own-cell draw membership, per-cell particle turns, cone admission, queue routing, alpha order, lifetime, or tick order.

A completed null-root safety frame has an empty landscape set. EnvCell owners still see their constant virtual result; outdoor owners fail closed. Login and portal-space frames still carry hasCompletedView=false and reject ordinary world-policy emitters.

3.3 C3 — delete AP-117's remaining reconstruction

Delete the complete TerrainModernRenderer.CollectVisibleCells route, including _visibleCellIds, VisibleCellIds, BeginVisibilityFrame, IWorldScenePassExecutor.TerrainVisibleCellIds, the null-root publication in WorldSceneRenderer, and the reconstruction-only tests. The flat terrain draw itself remains; only its fabricated visibility side channel goes.

After this deletion, AP-117 is retired: the walk path publishes the ported landscape product, and frames without that product publish none. Update AD-21 in the same commit so it no longer claims the login screen shows live sky and states that the safety draw cannot publish cell visibility.

3.4 C4 — delete the dead point-light feedback seam

Delete ObserveDrawableCells and ClearDrawableCells from IWorldRenderFrameBuilder, IWorldFrameEnvironmentPreparation, their runtime implementations, all calls, fakes, and tests. Keep point-light snapshot selection exactly resident-registry based. Correct AP-85 in the same commit to the code that actually remains: one resident, player-nearest 128-cap pool instead of retail's separate 7-dynamic/40-static pools and DBObj-granular residency. AP-68's owner-approved always-lit-interior policy is unchanged.

3.5 Explicit non-changes

S5-c1 must not change:

• WalkLandscape, WalkVisibilityMath, block/cell order, landscape event order, terrain draws, membership, portal flood, depth, alpha, shaders, RHI, DAT/package code, or streaming ownership;
• point-light capacity, sort anchor, curves, cell/object selection, or AP-68;
• directional-shadow selection (S5-c2 owns that consumer and its retained topology/per-frame visibility design);
• building degrade/complete-body selection (later S5 chunk);
• translucent-detail material combine/AP-232 (later S5 chunk);
• Facility probe and broader cleanup inventory (later S5 cleanup chunk).

No graphical client is launched from the implementation or review worktree.

4. Allowed files

Production changes are limited to the directly affected files:

• src/AcDream.Core/Vfx/ParticleSystem.cs;
• src/AcDream.App/Rendering/Vfx/ParticleVisibilityController.cs;
• src/AcDream.App/Rendering/RetailPViewRenderer.cs;
• src/AcDream.App/Rendering/WorldSceneRenderer.cs;
• src/AcDream.App/Rendering/WorldScenePassExecutor.cs;
• src/AcDream.App/Rendering/WorldRenderFrameBuilder.cs;
• src/AcDream.App/Rendering/TerrainModernRenderer.cs;
• comment-only truth correction in WalkFrameDriver.cs if required.

Tests may change in the directly affected Core/App VFX, renderer, frame-builder, and terrain-visibility files, plus compile-fallout fakes for the deleted interfaces. Documentation is limited to this packet, the plan ledger, acdream-architecture.md, oh1-construction-landscape-contract.md, and the divergence register. If implementation requires another production owner or a new deviation, stop and return the fact before expanding scope.

5. Tests and mutation evidence

Extend production-facing tests to prove:

1. an outdoor emitter is admitted only by the exact completed landscape set;
2. an EnvCell emitter remains update-eligible at authored range even when no indoor cell is in that set;
3. zero cell and no completed world view reject both cell families;
4. inclusive/unordered/raw-distance behavior and AP-116 Retail/Extended multipliers remain unchanged;
5. WorldSceneRenderer hands only RetailPViewFrameResult's landscape set to the particle owner, never the EnvCell set or diagnostic union;
6. abort/complete/reset preserve the previous-frame transaction;
7. no production CollectVisibleCells, TerrainVisibleCellIds, ObserveDrawableCells, or ClearDrawableCells symbol remains;
8. point-light snapshots still include resident lights regardless of the removed feedback set;
9. the warmed production particle-view path allocates 0 managed bytes.

Every new pin gets a real sabotage and exact first failure in the implementer commit body. At minimum mutate independently and restore exactly:

• make EnvCell eligibility depend on set membership;
• make outdoor eligibility constant true;
• feed the union instead of the landscape set at the renderer call site;
• restore one CollectVisibleCells production symbol;
• restore one ObserveDrawableCells production symbol;
• invert or exclude the inclusive authored-distance boundary.

6. Automated return and reviews

Implementer return:

• git diff --check;
• Release solution build, 0 warnings / 0 errors;
• focused Core VFX and App particle/frame/renderer/terrain tests;
• the real warmed 0-B particle-view pin;
• official hermetic lane;
• InstalledDat lane with exactly the documented global failure/skip set and no new failure;
• one clean commit, exact files/counts, and all mutation first failures.

Sequential review 1 — retail fidelity: re-check the named pseudo-C and paired bytes above, the CEnvCell vtable/ICF identity, previous-frame timing, cell-id discriminator, and every preserved x87/AP-116 edge. Review 2 — architecture, production, and gate honesty: prove one retained product, typed call-site reachability, no reconstructed/null-root answer, no point-light behavior change, reset/abort/lifecycle correctness, 0-B steady state, allowed scope, all register prose, all gate counts, and at least three mutation claims. A failed lens receives one bounded fix contract; a third fix round stops the chunk.

7. Remaining S5 decomposition after c1

1. S5-c2: exact landscape visibility consumption by directional-shadow caster selection without creating a second set or rebuilding retained topology on every camera-only change.
2. S5-c3: retail DrawBuilding degrade selection and complete-body null gate.
3. S5-c4: translucent detail single-stage framebuffer equivalence; retire AP-232.
4. S5-c5: delete Facility probes, production PortalVisibilityBuilder residue, obsolete fallbacks/flags/tests/claims; add architecture guards.
5. S5 closeout: full automated/lifecycle/performance program, G4 owner matrix, documentation closeout, then and only then merge to main.

8. Pre-review gate correction — retired-row count

The first official hermetic lane is retained as a failed artifact: 16,759 of 16,760 tests passed. The only failure is WalkStaticStreamPopulatorTests.WorldAlphaCyptDocumentationAndRegister_PinPerCellTruthAndThreeResiduals: its literal expected 162 active AP rows, while this chunk correctly retires AP-117 and leaves 161. This is a coupled documentation-test correction, not a renderer finding and not a review fix round.

The bounded correction may change only tests/AcDream.App.Tests/Rendering/Walk/WalkStaticStreamPopulatorTests.cs, replacing the stale active-row count with 161. Do not add a fabricated register row and do not change the three AP-241/AP-242/AP-243 assertions. Run the exact failed test first, then a fresh official hermetic lane under a new artifact name and the required InstalledDat lane. Preserve the original failed artifact and record both identities in the implementer return.

9. S5-c1 implementation result — 2026-09-04

The bounded implementation publishes WalkFrameDriver.VisitedLandscapeCellIds as the typed landscape product, retains it transactionally in the particle visibility owner, and applies the retail cell-family virtual: membership for land cells, constant true for non-null EnvCells. The null-root terrain reconstruction and the dead point-light drawable-cell feedback chain are deleted. AP-117 is retired; AP-85 and AD-21 now describe the surviving code.

The real warmed allocation pin initially exposed that enumerating the retained SortedSet<int> of world-simulation handles allocated on every Apply. The owner is now a sorted List<int> maintained at lifecycle mutation time, so the production Apply loop preserves stable handle order and measures 0 B without changing queue, router, draw, or particle tick behavior. This is an implementation-mechanism correction, not a retail behavior deviation.

Focused returns before the official lanes: Core VFX 111/111, App particle / frame / renderer / terrain 146/146, and the real warmed production allocation pin 1/1 at 0 B. Release built with 0 warnings / 0 errors. The first official hermetic artifact, artifacts/s5-c1-hermetic-20260904, is deliberately preserved at 16,759/16,760: its sole failure was the stale 162-row test literal after AP-117's retirement. Section 8 authorized only that coupled test correction; the exact failed pin then passed 1/1 with the truthful 161-row header and physical count. The one-shot corrected official lane at artifacts/s5-c1-hermetic-corrected-20260904 then passed 16,760/16,760, 0 skipped, across 14 assemblies. The inclusive InstalledDat lane at artifacts/s5-c1-installed-20260904 produced the documented global set: 385 passed, 10 failed, 1 skipped. The failures are TowerAscent, the two #383 layout sweeps, #458 Oh_doorway_still_first_frame_diff, and the six AlphaFlushCounts_* transcript Facts; the skip is Sweep_the_lookin_gate_decodes_against_the_street_fixture. No new failure or skip identity appeared.

Independent mutation ledger (each mutation restored exactly before the next):

1. EnvCell eligibility made set-dependent: ApplyRetailView_UsesLandscapeMembershipButEnvCellConstantVirtual first failed Assert.True, expected true / actual false, at ParticleSystemTests.cs:553.
2. Outdoor eligibility made constant true: the same test first failed Assert.False, expected false / actual true, at ParticleSystemTests.cs:559.
3. Renderer fed the diagnostic union: PViewWorld_PublishesOnlyLandscapeCellsToParticleVisibility first failed the HashSet equality at WorldSceneRendererTests.cs:279, expected [16842755], actual [16843008, 16842755].
4. A production CollectVisibleCells symbol was restored: Production_source_has_no_reconstructed_particle_visibility_feedback first failed at TerrainParticleCellVisibilityTests.cs:37, naming TerrainModernRenderer.cs.
5. A production ObserveDrawableCells symbol was restored: the same source guard first failed at line 37, naming WorldRenderFrameBuilder.cs.
6. The inclusive boundary was changed from <= to <: ApplyRetailView_UsesOwnerVisibilityAndInclusiveAuthoredDistance first failed Assert.True, expected true / actual false, at ParticleSystemTests.cs:519.

10. Sequential review 1 — retail lens and fix round 1

The retail lens found no behavioral retail-fidelity defect. It independently matched the paired executable/PDB identity and bytes for ShouldDrawParticles, UpdateParticles, both cell-family virtuals, the previous-completed-frame transaction, the low-word discriminator, examination bypass, x87 distance edges, AP-116, the exact landscape handoff, and unchanged particle draw/queue/tick behavior. The lens returned FAIL on comment truth only:

1. ParticleVisibilityController.UseWorldView still says an outdoor fallback can publish the authoritative product, although S5-c1 deleted it.
2. WalkFrameDriver.CopyVisibleCellsTo still calls the diagnostics union the complete CObjCell::IsInView answer and says particles, lights, and shadows consume it. Particles now consume only the landscape half, EnvCell particle eligibility is constant true, point lights use the resident registry, and directional shadows remain S5-c2.
3. ParticleSystem calls the sorted-list lifecycle insertion/removal cost binary even though only the insertion search is binary and list shifts / removal are linear. Its adjacent blanket O(log E) lifecycle sentence must remain scoped to the SortedSet indexes rather than the new list.

Fix round 1 is comment-only. It may change exactly ParticleVisibilityController.cs, WalkFrameDriver.cs, and ParticleSystem.cs, plus this packet's result section. Do not change behavior, tests, register rows, architecture prose, or any other file. Correct the three descriptions to the surviving ownership/cost model, run git diff --check and the same focused retail-review classes (47 Core particle tests, 38 App visibility/terrain/frame/renderer tests, and 3 AP-116 settings/live-object tests), commit once, then return to a narrow retail comment-truth re-review. The production/gate-honesty lens remains undispatched until that re-review passes. A third fix round still stops the chunk.

10.1 Fix-round-1 implementation result

The three stale descriptions are corrected without behavior or assertion changes. CopyVisibleCellsTo describes a diagnostic union and names the distinct particle, point-light, and future directional-shadow consumers. ParticleSystem scopes the logarithmic lifecycle statement to its SortedSet indexes and records the sorted list's binary-search plus linear-shift insertion and linear search/compaction removal costs. Focused gate results: Core ParticleSystemTests 47/47, App visibility/terrain/frame/renderer 38/38, and AP-116 settings/live-object 3/3; git diff --check is clean. The first narrow re-review found the UseWorldView result sentence still misstated null-root transaction state; fix round 2 below supersedes that sentence.

11. Retail narrow re-review — fix round 2 (last allowed)

The narrow retail re-review passed the four-file scope, behavior/test/register invariance, diagnostic-union wording, sorted-list cost wording, diff check, and the focused 47 + 41 tests. It found one remaining MINOR comment-truth error: ParticleVisibilityController.UseWorldView and §10.1 say the null-root safety draw omits/excludes the completed product. Production begins visibility before root resolution and calls UseWorldView for every non-login built frame, so a null-root safety frame completes hasCompletedView=true with an empty landscape set. Login/portal frames carry hasCompletedView=false. This distinction is already the bound §3 behavior: null-root invents no fallback cells.

Fix round 2 is the last allowed round and is prose-only. It may change exactly the UseWorldView XML comment in ParticleVisibilityController.cs and this packet's result prose. State that non-login world frames participate in the completed transaction; the retail walk publishes its exact landscape set when present, while null-root completes an empty set without reconstruction. Do not change code behavior, tests, register/architecture prose, or any other file. Run git diff --check, Core particle 47/47, and the combined App/AP-116 41/41; commit once and return to the same narrow retail lens. Any further finding that would require a third fix round stops S5-c1 and is written up.

11.1 Fix-round-2 implementation result

UseWorldView now states the production transaction exactly: every non-login world frame participates; a PView walk contributes its exact landscape set, while a null-root safety frame completes hasCompletedView=true with an empty set and no reconstructed fallback. Login and portal-space frames retain hasCompletedView=false. No behavior or assertion changed. Core particle tests passed 47/47, the combined App visibility/terrain/frame/renderer plus AP-116 lane passed 41/41, and git diff --check is clean.

12. Owner-authorized documentation/evidence exception — 2026-09-04

The final production/gate-honesty lens found no production-code or test defect but returned FAIL after fix round 2 on two correction-worthy truth gaps:

1. architecture and AD-21 say null-root publishes no cell-visibility answer, while production completes hasCompletedView=true with an empty landscape set; and
2. the official lane summaries identify dirty bases, but the packet does not independently bind those dirty source deltas to implementation commit 9aadc917a.

Per the campaign rule, S5-c1 stopped and the campaign branch recorded that stop at efb075619. The owner then explicitly authorized a documentation/evidence-only exception: "correct docs and continue." The stop and both failed-lens results remain in history.

The exception is bounded to:

• truth-correcting the null-root sentence in docs/architecture/acdream-architecture.md;
• truth-correcting AD-21 in docs/architecture/retail-divergence-register.md;
• recording this exception and its evidence in this packet; and
• updating only the S5-c1/S5 ledger rows in docs/plans/2026-09-01-campaign-overhaul-world-solidity.md.

No production code, tests, other register row, architecture section, or prior artifact may change. The correction must state that every non-login world frame participates, a walk contributes its exact landscape set, and null-root completes an empty set without reconstruction; login/portal remain false.

After the documentation correction is committed, create fresh official evidence from that clean exact commit (not a dirty pre-commit tree):

• artifacts/s5-c1-exception-hermetic-20260904 — hermetic lane;
• artifacts/s5-c1-exception-installed-20260904 — InstalledDat lane.

Both summaries must record the correction commit and WorktreeDirty=false; their manifests must verify completely. The older dirty-base artifacts remain preserved as historical evidence but are superseded for landing provenance. One narrow independent production/gate-honesty re-review verifies only the authorized documentation diff, exact clean artifact identity/counts/hashes, and absence of code/test changes. PASS permits landing and the graphical gate; any behavioral change or further correction-worthy finding stops again.

12.1 Exception implementation result — clean evidence complete

The authorized documentation correction aligns the architecture and AD-21 with production's existing transaction without changing code or tests: every non-login normal-world frame participates, the walk contributes its exact landscape set when present, and null-root completes hasCompletedView=true with an empty set and no reconstruction; login and portal-space retain hasCompletedView=false.

The pre-exception official artifacts remain preserved as historical evidence, including their dirty-base identities. They do not become clean commit-bound evidence by prose assertion. Both replacement lanes ran from exact correction commit d6592d3ac56bc400bfdaab7cff59306319b5b96d with WorktreeDirty=false and now supersede the older dirty artifacts for landing provenance:

• artifacts/s5-c1-exception-hermetic-20260904 — PASS, 16,760 passed, 0 failed, 0 skipped across 14 assemblies. Its 32-entry SHA-256 manifest verifies with zero missing or mismatched files.
• artifacts/s5-c1-exception-installed-20260904 — 385 passed, the same 10 documented failures, and the same 1 documented skip across 14 assemblies. Its 30-entry SHA-256 manifest verifies with zero missing or mismatched files. Compare-Object over every non-passing TRX identity against the historical inclusive artifact returned zero differences.

The first clean InstalledDat invocation omitted ACDREAM_RUN_INSTALLED_DAT_TESTS=1; 97 live-DAT tests therefore self-skipped with their explicit opt-in message. That invalid evidence is preserved at artifacts/s5-c1-exception-installed-invalid-missing-env-20260904 (291 passed / 8 failed / 97 skipped) and is not used for acceptance. The canonical invocation pinned both ACDREAM_RUN_INSTALLED_DAT_TESTS=1 and ACDREAM_DAT_DIR=C:\\Turbine\\Asheron's Call; it produced the exact documented identity above without a product change or product retry.

Production and tests remain byte-identical to the authorized contract parent. The plan ledger therefore advances to clean evidence complete, with only the narrow independent production/gate-honesty review pending before landing and the graphical gate.