feat(rendering): contain incremental render scene

Pin Arch behind acdream-owned identities, deltas, queries, generation gates, and memory diagnostics. The new five-archetype store is unbound and non-drawing so static publication can be shadowed without changing production behavior.

Co-authored-by: Erik Nilsson <erikn@users.noreply.github.com>
This commit is contained in:
Erik 2026-07-24 21:42:42 +02:00
parent f9b68f8f2a
commit dbd8318417
7 changed files with 1698 additions and 2 deletions

View file

@ -18,8 +18,9 @@ retail-faithful gameplay
|---|---|---|
| F0a — partition-input referee | complete | Diagnostic-only `CurrentRenderSceneOracle`; no production draw decision changed. |
| F0b — survivor/dispatcher/selection referee | complete | Exact PView routes, dispatcher candidates and final group payloads, material/alpha/clip/light/selection fields, and accepted picking parts. Release gate: 3,690 App tests / 3 skips and 8,174 complete-solution tests / 5 skips. |
| F1 — scene types and contained adapter | active | No render-scene storage or shadow projection exists yet. |
| F2F5 | pending | Delta publication and continuous shadow comparison have not started. |
| F1 — scene types and contained adapter | complete | `Arch 2.1.0` is pinned in App only behind acdream contracts. Five narrow archetypes, generation/incarnation/sequence gates, borrowed-query invalidation, memory accounting, deterministic digesting, and update-thread enforcement pass 11 focused tests. Release gate: 3,701 App tests / 3 skips and 8,185 complete-solution tests / 5 skips. |
| F2 — static projection journal | active | Static publication/retirement owners do not emit render deltas yet. |
| F3F5 | pending | Live/equipped publication, dynamic indices, and continuous shadow comparison have not started. |
| G0G5 | pending | No production consumer has switched. |
The exact pre-F/G runtime rollback anchor remains `e7d9d6fa`. F0 is
@ -314,6 +315,17 @@ performance regression with comparison disabled.
**Commit gate:** the scene is unbound and non-drawing; full suite green.
**Landed evidence:** the package/API/license decision is recorded in
`docs/research/2026-07-24-arch-render-scene-dependency.md`. Production
composition does not construct `ArchRenderScene`; F1 therefore changes no
runtime path. Source/reflection architecture tests confine all Arch types and
primitive-ID extraction to `AcDream.App/Rendering/Scene/Arch`. Pure App tests
cover every structural/channel operation, generation replacement, stale
incarnation and sequence rejection, borrowed-query invalidation, deterministic
digest order, retained-memory accounting, and cross-thread mutation rejection.
The Release gate is 3,701 App tests / 3 skips and 8,185 complete-solution tests
/ 5 skips.
### F2 — Static projection journal
1. Append Register deltas from the existing final landblock spatial publication

View file

@ -0,0 +1,77 @@
# Arch render-scene dependency decision
**Date:** 2026-07-24
**Scope:** Modern Runtime Slice F1 only
## Decision
Pin `Arch` version `2.1.0` directly in `AcDream.App`. Do not reference it from
Core, UI abstractions, plugins, or any other production project. Do not use
Arch systems, command buffers, parallel queries, jobs, events, source
generators, persistence, relationships, or extension packages.
The only allowed Arch namespace is:
```text
src/AcDream.App/Rendering/Scene/Arch/
```
Everything outside that folder uses acdream-owned `IRenderScene`, wrapper
identities, packed component values, deltas, borrowed queries, digests, and
memory-accounting values. Arch entities and primitive wrapper values cannot
cross that boundary.
## Verification
- Official package: [NuGet `Arch 2.1.0`](https://www.nuget.org/packages/Arch/2.1.0)
- Official source/tag:
[genaray/Arch `v2.1.0`](https://github.com/genaray/Arch/tree/v2.1.0)
- License:
[Apache License 2.0](https://github.com/genaray/Arch/blob/v2.1.0/LICENSE.MD)
- Selected source tag commit:
`04d52e7268eb6f376ca4841a0c204334120c5e9d`
The selected package supplies .NET 6 and .NET Standard 2.1 assets, both
compatible with acdream's .NET 10 App target. The v2.1.0 source was inspected
for the exact API used by the adapter:
- `World.Create`
- generic `World.Create<T...>`
- `World.Set<T>` / `World.Get<T>`
- `World.Destroy(Entity)` / `World.Destroy(World)`
- `World.Size`, `World.Capacity`, and `World.Archetypes`
- archetype chunk count and chunk-size accounting
The resolved dependency graph was captured with
`dotnet list package --include-transitive`. It resolves:
```text
Arch 2.1.0
Arch.LowLevel 1.1.5
Collections.Pooled 2.0.0-preview.27
CommunityToolkit.HighPerformance 8.4.0
Microsoft.Extensions.ObjectPool 7.0.0
ZeroAllocJobScheduler 1.1.2
```
No package in the resolved App graph was reported vulnerable by NuGet's
`--vulnerable --include-transitive` audit on 2026-07-24. The transitive job
scheduler is not initialized or called by acdream; Slice F uses only
single-threaded structural operations and direct component access on the
existing update thread.
## Containment proof
`RenderSceneArchitectureTests` enforces all of the following:
1. `Arch` is a direct package reference in `AcDream.App` only.
2. Arch namespaces occur only in the contained adapter folder.
3. Reflection finds no Arch field, property, parameter, or return type outside
that namespace.
4. Raw wrapper identity extraction occurs only in the adapter (apart from the
private contract declarations themselves).
This is storage selection, not simulation architecture. `LiveEntityRuntime`,
`GpuWorldState`, gameplay identities, retail PView, GL ownership, and all
behavioral owners remain authoritative and unchanged.