docs(runtime): close J3.3 and hand off J3.4

Record exact projection-store ownership, automated and connected evidence, rollback chain, and the executor-ready canonical object-table plan. Reconcile milestones, roadmap, architecture, divergence pointers, AGENTS/CLAUDE, and durable handoff state. Co-authored-by: Codex <codex@openai.com>
2026-07-25 22:29:34 +02:00 · 2026-07-25 22:29:34 +02:00 · d9bf4c4960
commit d9bf4c4960
parent e937cc36df
15 changed files with 757 additions and 114 deletions
--- a/docs/research/2026-07-25-slice-j3-3-complete-j3-4-handoff.md
+++ b/docs/research/2026-07-25-slice-j3-3-complete-j3-4-handoff.md
@ -0,0 +1,138 @@
+# HANDOFF — J3.3 complete; start J3.4 canonical object-table ownership
+
+## Outcome
+
+Stop here. J3.3 is complete and certified.
+
+Final code commits:
+
+1. `420e5eea70fd2c29cf9c8614e6298a1f84d64045`
+   — App projection sidecars and presentation worksets use exact
+   `RuntimeEntityKey`.
+2. `e937cc36df39cf6ea1eaba2f9c0243d1929da702`
+   — spatial residence, visibility, quiescence, rebucketing, retirement, and
+   origin recenter preserve that same exact key.
+
+Do not reopen J3.3 unless a reproducible gate fails. The next slice is J3.4.
+
+## Read in this order
+
+1. `AGENTS.md`
+2. `docs/plans/2026-07-25-modern-runtime-slice-j3-object-table.md`
+3. `docs/plans/2026-07-25-modern-runtime-slice-j3.md`
+4. `docs/research/2026-07-25-slice-j3-3-exact-projection-store.md`
+5. `claude-memory/project_modern_runtime_architecture.md`
+6. `claude-memory/project_live_entity_runtime.md`
+7. `docs/architecture/acdream-architecture.md`
+8. `docs/architecture/code-structure.md`
+
+The first plan is the authoritative J3.4 execution plan. The parent plan
+defines J3.5/J3.6 and final acceptance.
+
+## Current architecture
+
+- `RuntimeEntityDirectory` is the only server-GUID/incarnation/local-ID
+  authority.
+- `RuntimeEntityRecord` is presentation-free.
+- `LiveEntityProjectionStore` is the only materialized App sidecar store.
+- Every App materialized owner uses exact `RuntimeEntityKey`.
+- `GpuWorldState` retains the exact key across all spatial lifetime changes.
+- `LiveEntityRuntime` is an App projection/lifecycle host, not canonical
+  identity.
+- No queue, copied gameplay world, extra frame, or rendering behavior change
+  was introduced.
+
+The remaining J3.4 split is visible in two places:
+
+- `LiveEntityRuntime` still constructs `RuntimeEntityDirectory`.
+- `GameWindow` still constructs the live `ClientObjectTable`.
+
+J3.4 replaces those two independent construction points with one
+presentation-free Runtime entity/object lifetime-group root, then makes all App
+controllers and Runtime session routing borrow its exact instances.
+
+## Required behavior
+
+Preserve verbatim:
+
+- canonical create acceptance before object-table CreateObject mutation;
+- `CreateIntegrationVersion` revalidation after synchronous callbacks;
+- logical DeleteObject mutation before App projection teardown;
+- pickup/parent leave-world without object-table deletion;
+- optimistic move, authoritative confirm, and rejection rollback;
+- ViewContents/container replacement and nullable unknown-object move notices;
+- current pre-Connect subscription order;
+- object-table clear before graphical projection reset;
+- synchronous press-time UI and controller reads.
+
+Do not move retained UI, item icons, paperdolls, grids, cooldown drawing,
+selection presentation, or higher-level inventory transactions into Runtime in
+J3.4. Those are borrowers now and later J4 work.
+
+## Baseline and gates
+
+Final J3.3 baseline:
+
+- focused exact ownership/streaming: 104 passed;
+- App: 3,761 passed / 3 skipped;
+- complete Release: 8,444 passed / 5 skipped;
+- Release build: pass;
+- connected report:
+  `logs/connected-world-gate-20260725-221008/report.json`;
+- connected result: two sessions, seven checkpoints, both graceful exit code
+  zero, zero failures, zero render-shadow mismatches, zero pending deltas.
+
+Standard commands:
+
+```powershell
+dotnet build AcDream.slnx -c Release --no-restore
+dotnet test AcDream.slnx -c Release --no-build
+```
+
+Run the focused Runtime/Core/App matrix listed in the J3.4 plan before the full
+suite. Commit the J3.4 code before running the connected gate so the report
+identifies one immutable binary. Use credentials supplied by the user/session;
+never write them into source or documentation.
+
+## Worktree cautions
+
+These tracked paths can appear modified from Windows metadata/line-ending
+behavior while remaining content-identical to the index:
+
+- `src/AcDream.App/Interaction/PlayerInteractionMovementSink.cs`
+- `src/AcDream.App/Rendering/LiveAnimationPresentationContext.cs`
+- `src/AcDream.Core/Physics/CellArray.cs`
+- `src/AcDream.Core/Vfx/ParticleSystem.cs`
+- `tests/AcDream.Core.Tests/Vfx/ParticleSystemTests.cs`
+
+Do not stage or rewrite them unless `git diff -- <path>` shows a real task
+change.
+
+`.test-out/`, nested `.test-out/`, and `logs/` contain local test/evidence
+artifacts, including very large prepared packages. Do not stage them and do not
+recursively delete them without first verifying the exact absolute target.
+
+## Exact rollback
+
+If J3.3 itself must be rolled back, revert newest first:
+
+```text
+git revert e937cc36df39cf6ea1eaba2f9c0243d1929da702
+git revert 420e5eea70fd2c29cf9c8614e6298a1f84d64045
+```
+
+For a J3.4 failure, revert only the new J3.4 commit. Do not use the J3.3
+rollback as a shortcut.
+
+## Final J3 goal
+
+J3.4 establishes one Runtime entity/object ownership root. J3.5 publishes one
+ordered per-session entity/object delta stream consumed by graphical and
+direct hosts without a second queue or mirror. J3.6 proves failure recovery,
+no-window lifecycle, multiple-instance isolation, exact teardown convergence,
+Release parity, and the connected route.
+
+The J3 campaign is complete only when J3.6 proves zero leaked canonical
+records, tombstones, App projections, resources, container entries, parent
+candidates, deltas, and subscriptions. That is the next clean boundary before
+J4 gameplay-state services and later Slice K Linux/headless multi-session work.
--- a/docs/research/2026-07-25-slice-j3-3-exact-projection-store.md
+++ b/docs/research/2026-07-25-slice-j3-3-exact-projection-store.md
@ -0,0 +1,128 @@
+# Modern runtime J3.3 exact projection-store closeout
+
+## Result
+
+J3.3 is complete in two production commits:
+
+1. `420e5eea70fd2c29cf9c8614e6298a1f84d64045` — exact-key App
+   projection store and presentation-owner cutover.
+2. `e937cc36df39cf6ea1eaba2f9c0243d1929da702` — exact-key spatial
+   residence, visibility, quiescence, rebucketing, and retirement correction.
+
+The second commit is the final exact binary certified by the connected gate.
+
+`AcDream.Runtime.Entities.RuntimeEntityDirectory` remains the sole owner of
+current server GUID, `INSTANCE_TS` incarnation, Runtime local ID, reverse
+lookup, accepted snapshot/timestamps, parent state, session epoch, tombstones,
+and per-GUID operation versions.
+
+`AcDream.App.World.LiveEntityProjectionStore` now owns materialized graphical
+sidecars only. Its key is the complete `RuntimeEntityKey`:
+
+```text
+Runtime local ID + INSTANCE_TS incarnation
+```
+
+There are three explicit states:
+
+1. canonical-only Runtime registration with no App sidecar;
+2. one materialized App sidecar under its exact key;
+3. retryable teardown retaining only the unfinished suffix for that exact key.
+
+The temporary `ActiveRecordView`, `_activeRecords`, detached
+`LiveEntityRecord(EntitySpawn)` fixture path, and broad materialized/visible
+`WorldEntity` collection APIs are deleted. Consumers use focused borrowed
+queries or allocation-free exact-key record views.
+
+## Exact owner cutover
+
+The following App owners now carry the exact key:
+
+- world projection and loaded/pending spatial residence;
+- spatial visibility transitions and world-generation quiescence;
+- hydration and recovery;
+- animation and spatial-animation schedules;
+- remote motion, remote teleport, and movement observations;
+- projectile and ordinary-root worksets;
+- entity effect profiles and moving lights;
+- equipped-child roots and render registrations;
+- render-scene journal identity;
+- radar, targeting, selection, liveness, and teardown lookups.
+
+`GpuWorldState` preserves the exact key through loaded-to-loaded rebucketing,
+pending residence, landblock retirement/reload, persistent rescue, and
+full-origin recenter. A delayed visibility edge therefore cannot match a later
+incarnation that reused the same numeric local ID. DAT-static entities retain
+their existing non-Runtime path and are not assigned a fabricated server-live
+identity.
+
+No asynchronous queue, copied gameplay world, extra input frame, local-ID
+allocation-order change, renderer order change, or gameplay behavior change
+was introduced.
+
+## Automated acceptance
+
+At final commit `e937cc36`:
+
+- focused ownership/streaming tests: 104 passed;
+- App tests: 3,761 passed / 3 skipped;
+- complete Release solution: 8,444 passed / 5 skipped;
+- Release solution build: pass.
+
+Coverage includes canonical-only registration, exact sidecar claim, same-
+incarnation refresh, factory/resource rollback, local-ID wrap and stale-key
+rejection, loaded/pending rebucketing, landblock detach/reload, origin
+recenter, reentrant visibility callbacks, GUID replacement, hydration,
+animation/effect/light/equipped-child ownership, and retryable teardown.
+
+Source guards reject a GUID-keyed App `LiveEntityRecord` authority map and
+local-ID-only ownership in the materialized presentation/spatial worksets.
+The divergence-register audit found no new behavioral divergence: J3.3 changes
+ownership and identity plumbing only. AD-32's moved Runtime source pointers
+were refreshed without changing its scope.
+
+## Connected lifecycle acceptance
+
+Raw evidence:
+`logs/connected-world-gate-20260725-221008/report.json`.
+
+Result: PASS on exact commit
+`e937cc36df39cf6ea1eaba2f9c0243d1929da702`.
+
+- Two fresh processes/sessions completed.
+- Seven of seven checkpoints passed.
+- Both processes exited gracefully with exit code zero.
+- The report contains zero failures.
+- Every checkpoint has zero render-scene shadow mismatches.
+- Every checkpoint converged with zero pending render deltas.
+- The only warning is 25 expected world-edge landblock misses.
+
+This certifies fresh login, outdoor/dungeon travel, same-location revisit,
+graceful logout, and fresh-process reconnect on the exact final binary.
+
+## Exact rollback
+
+Revert newest first:
+
+```text
+git revert e937cc36df39cf6ea1eaba2f9c0243d1929da702
+git revert 420e5eea70fd2c29cf9c8614e6298a1f84d64045
+```
+
+Do not revert J3.2 unless canonical Runtime identity itself is also being
+rolled back.
+
+## Next slice
+
+Start J3.4 in
+`docs/plans/2026-07-25-modern-runtime-slice-j3.md`.
+The executor-ready transfer prompt is
+`docs/research/2026-07-25-slice-j3-3-complete-j3-4-handoff.md`.
+
+J3.4 moves the existing canonical `ClientObjectTable` and its placement/
+container lifetime under one Runtime entity/object group. App remains a
+synchronous borrower for retained UI, item icons, paperdolls, grids, cooldown
+drawing, and interaction presentation. It must preserve object add/update/
+remove, container replacement, optimistic move rollback, stack responses,
+GUID reuse, session clear, and press-time event ordering without adding a
+queue or copied inventory model.