acdream/docs/plans/2026-07-25-modern-runtime-slice-j3-projection-store.md

# Modern runtime J3.3 — exact-key App projection store

**Status:** READY AFTER J3.2 CONNECTED GATE
**Parent:** `2026-07-25-modern-runtime-slice-j3.md`
**Required base:** `f46ddb5cdb1e145752bea49aeb1d62bfe71284d3`

## Objective

Make every materialized App-side live-object owner use the exact
`RuntimeEntityKey` (`Runtime local ID + INSTANCE_TS`) issued by
`RuntimeEntityDirectory`.

Runtime remains the only server-GUID authority. App may carry GUID as immutable
metadata for diagnostics and outbound commands, but no App dictionary may use
GUID to decide which incarnation is current.

No asynchronous projection queue, extra input frame, renderer behavior change,
or local-ID allocation-order change is permitted.

## Fixed model

There are three distinct states:

1. **Canonical-only registration** — Runtime accepted an incarnation, but no
   graphical host has claimed a local ID. No materialized projection exists.
2. **Materialized projection** — Runtime has claimed the local ID and App owns
   exactly one sidecar under the resulting `RuntimeEntityKey`.
3. **Retryable teardown** — Runtime retains the exact canonical tombstone while
   App retains only the unfinished teardown suffix for that exact key. A
   registration that failed before local-ID claim has no graphical tombstone.

A small synchronous construction context may carry a canonical record between
registration and materialization. It is not a retained App identity map.

## Execution

### 1. Introduce `LiveEntityProjectionStore`

- Store materialized sidecars in
  `Dictionary<RuntimeEntityKey, LiveEntityRecord>`.
- Resolve GUID only by asking `RuntimeEntityDirectory` for the current
  canonical record, reading its exact key, then querying the store.
- Reject key reuse, local-ID mismatch, incarnation mismatch, and stale
  canonical records.
- Preserve insertion order and allocation-free borrowed enumeration.
- Retain teardown progress under the exact key; use canonical-reference storage
  only for the exceptional pre-materialization registration rollback which has
  no key.

### 2. Move sidecar creation to local-ID claim

- `RegisterLiveEntity` returns canonical registration facts without allocating
  a graphical sidecar.
- `MaterializeLiveEntity` claims the Runtime local ID at the same point as
  today, creates the exact-key sidecar, then calls the projection factory.
- Same-incarnation refresh before materialization mutates only Runtime state.
- Same-incarnation refresh after materialization resolves the existing sidecar
  through its exact key.
- Factory, resource-registration, and rollback failures retain exactly the
  currently unfinished ownership suffix.

### 3. Re-key every presentation workset

Convert the following from GUID/local-ID-only maps to exact-key maps:

- materialized and visible `WorldEntity` projections;
- animation and spatial-animation owners;
- remote-motion and spatial-remote-motion owners;
- projectile and spatial-projectile owners;
- ordinary root object workset;
- effect profile, visibility publication, hydration, and teardown lookups.

Local-ID-only iteration views validate the incarnation through the projection
store before yielding. No stale entry can match a replacement that reused the
same numeric local ID after wraparound.

### 4. Cut consumers over to borrowed queries

- Replace direct GUID dictionary access in selection, radar, combat targeting,
  local-player animation/mode, teleport, physics update, diagnostics, and
  composition with typed `TryGet...`, exact-key, or borrowed-enumeration
  methods.
- Keep synchronous press-time reads; do not publish a copied frame snapshot.
- Preserve server GUID in yielded metadata where outbound commands need it.
- Remove `MaterializedWorldEntities`, `WorldEntities`, and component
  dictionaries once all consumers use the focused queries.

### 5. Delete the J3.2 compatibility view

- Delete `ActiveRecordView`.
- Delete `_activeRecords` and every App GUID-keyed live-object/component map.
- Remove the detached `LiveEntityRecord(EntitySpawn)` fixture constructor;
  component tests construct exact Runtime identities through a shared fixture.
- Add source guards rejecting:
  - App `Dictionary<uint, LiveEntityRecord>`;
  - App live-object/component maps keyed by server GUID;
  - an App reverse GUID/local-ID map;
  - a projection store key other than `RuntimeEntityKey`.

### 6. Failure and parity gate

Exercise:

- create without materialization;
- same-incarnation refresh before and after materialization;
- factory throw before sidecar publication;
- resource register failure with successful and failed rollback;
- loaded/pending rebucket and visibility reentrancy;
- delete/recreate with the same GUID;
- local-ID wraparound and stale-key rejection;
- parent/pickup/Hidden transitions;
- session clear during every projection callback;
- retryable teardown with a live replacement.

Run:

- focused Runtime and App identity/projection tests;
- all App tests;
- Release solution build;
- complete Release tests;
- exact-binary connected lifecycle/reconnect;
- render-scene identity/digest referee at every checkpoint.

## Acceptance

- Runtime owns the only GUID/incarnation/local-ID authority.
- Every materialized App owner is keyed by exact `RuntimeEntityKey`.
- App retains no GUID identity dictionary or reverse local-ID authority.
- A stale key cannot query, update, withdraw, or tear down a replacement.
- Local-ID allocation order is unchanged.
- No new allocation appears in steady-state live-object traversal.
- No callback is delayed to another frame.
- All automated and connected gates pass on the exact commit.