acdream/docs/plans/2026-07-26-modern-runtime-slice-j3-delta-stream.md

Modern runtime J3.5 — committed entity/object deltas and borrowed views

Status: COMPLETE — ce3ac310d92722ffb637e81cb1957458874dd220 Parent: 2026-07-25-modern-runtime-slice-j3.md Required production base: 5ef8b5371d8990f0380acd939e71cd711289d429 Prior closeout: docs/research/2026-07-26-slice-j3-4-canonical-object-lifetime.md

Objective

Publish one synchronous, monotonic, generation-stamped stream from the canonical Runtime entity/object lifetime and make both graphical and no-window/direct hosts observe those same committed facts.

IGameRuntimeView.Entities and IGameRuntimeView.Inventory must read the Runtime-owned RuntimeEntityDirectory and ClientObjectTable directly. CurrentGameRuntimeEventAdapter must stop reconstructing entity changes from App projection visibility and inventory changes from an App-owned event seam.

This slice adds no later-frame queue, copied world, inventory mirror, input delay, renderer dependency, or gameplay behavior change.

Current seam at the production base

• RuntimeEntityObjectLifetime owns the exact directory and object table.
• CurrentGameRuntimeViewAdapter.EntityView still reads App LiveEntityRuntime, so a direct host cannot enumerate canonical entities without constructing the graphical projection host.
• Its inventory view reads the right table but asks LiveEntityRuntime to recover incarnation metadata.
• CurrentGameRuntimeEventAdapter owns a separate sequencer and reconstructs:
  • entity events only from ProjectionVisibilityChanged; and
  • inventory events by subscribing directly to object-table callbacks.
• Registered, refreshed, parented, picked-up, state-updated, cellless, and authoritative-delete canonical edges therefore do not have one complete Runtime stream.
• Runtime local IDs are still claimed at App materialization rather than at canonical registration, even though direct and graphical hosts require one stable cross-host identity.

The J1 adapter was intentionally temporary. J3.5 deletes these superseded entity/object adapter responsibilities.

Fixed contracts

One canonical stream owner

Add one instance-scoped stream under AcDream.Runtime.Entities, owned by RuntimeEntityObjectLifetime.

It exposes a narrow subscription equivalent to:

public interface IRuntimeEntityObjectObserver
{
    void OnEntity(in RuntimeEntityDelta delta);
    void OnInventory(in RuntimeInventoryDelta delta);
}

public interface IRuntimeEntityObjectEventSource
{
    IDisposable Subscribe(IRuntimeEntityObjectObserver observer);
}

Entity and inventory deltas share one sequence owner. There is no entity queue plus inventory queue and no App repeater. Every stamp carries the exact RuntimeGenerationToken and current Runtime frame number.

Sequence rules:

• sequence starts at one for each live session generation;
• entity and inventory commits consume the same monotonic sequence;
• rejected/stale packets consume no sequence;
• callback reentrancy appends later sequence values in actual commit order;
• session reset publishes its committed withdrawals/removals/clear edge, then the retired generation is sealed;
• a replacement generation cannot publish through the retired stream context.

Canonical entity identity and snapshot

Runtime claims a local ID when it creates the canonical active record, before any graphical projection callback. The ID remains stable for that incarnation until canonical teardown; graphical hydration failure must not release a still-active Runtime identity.

The public entity view is canonical and presentation-free:

• server GUID;
• Runtime local ID;
• exact INSTANCE_TS incarnation;
• full cell;
• final physics state;
• accepted position/snapshot facts.

Graphical hydration, loaded/pending visibility, and render-resource state do not become gameplay truth. If retained diagnostic contracts still need attached-host counts, those are supplied by a separate projection acknowledgement/diagnostic seam and are not mixed into canonical entity identity.

Commit ordering

An entity delta is created only after the exact Runtime record mutation commits. The graphical projection host receives that same immutable committed delta synchronously and returns an exact acknowledgement; public observers then observe the same sequence. There is no second conversion step and no frame boundary.

Required entity edges:

• Registered after active-record/local-ID commit;
• Updated after same-incarnation CreateObject, ObjDesc, vector, movement, accepted position, parent, or equivalent canonical refresh;
• Rebucketed after a canonical full-cell change;
• Hidden after a committed Hidden state transition;
• Withdrawn after pickup/accepted parent/cellless exit-world while the incarnation remains logically alive;
• Deleted after authoritative identity retirement and retained-object removal acceptance;
• generation replacement orders old Deleted/withdrawal before new Registered.

Loaded-to-pending renderer visibility is not a canonical withdrawal and emits no gameplay entity delta.

Required inventory edges remain the exact object-table callback order:

• Added;
• Updated;
• Moved;
• Removed with exact removed generation;
• Cleared.

Unknown-object move notices retain the object ID and placement facts rather than disappearing because no ClientObject instance exists.

Borrowed views

The Runtime lifetime group exposes concrete allocation-free IRuntimeEntityView and IRuntimeInventoryView implementations:

• entity enumeration walks RuntimeEntityDirectory.ActiveRecords;
• entity lookup resolves directly through the directory;
• inventory enumeration/lookup walks ClientObjectTable;
• inventory incarnation comes from the exact Runtime directory or the object's retained generation, never an App sidecar;
• visitors receive value snapshots and may not retain mutable owners.

CurrentGameRuntimeViewAdapter borrows those view objects. It retains only the still-unmoved J4+ chat/movement/portal/lifecycle composition.

Execution

1. Pin the pre-cutover normalized oracle

Add a focused deterministic fixture covering:

• create, same-incarnation refresh, and generation replacement;
• ObjDesc/property and accepted state/vector/movement/position updates;
• parent, pickup, cellless withdrawal, and re-entry;
• object add/update/move/remove/clear;
• optimistic move, confirm, rejection rollback, and container replacement;
• authoritative delete and delete/recreate with the same GUID;
• reset and next-generation reuse;
• callback reentrancy.

Record both the canonical final state and exact event order. Preserve existing retail-facing object-table callback order; add missing canonical entity edges without treating projection visibility as gameplay truth.

2. Add the Runtime entity/object stream

• Add the stream owner and narrow observer/source contracts in Runtime.
• Give it one per-generation sequencer and explicit session-generation/frame context.
• Use copy-on-write subscriber storage so steady dispatch allocates no observer list and unsubscribe is exact.
• Reject duplicate subscriptions, cross-owner subscriptions, stale generations, and dispatch after disposal.
• Keep callback execution on the existing update/network-drain thread.
• Revalidate generation/incarnation/operation version after any callback that can re-enter Runtime.

3. Move identity allocation to canonical registration

• Claim the Runtime local ID in the same transaction that installs an active canonical record.
• Preserve current allocation range and wrap/exhaustion behavior.
• Stop releasing the ID when only App materialization rolls back.
• Release it only when the canonical incarnation reaches terminal teardown.
• Prove pending/unhydrated and direct-host entities still have exact keys.
• Prove GUID reuse gets a new key and stale keys never resolve.

4. Publish canonical entity commits

• Centralize accepted canonical mutations behind RuntimeEntityObjectLifetime transaction methods.
• Publish only after state commits and only while the exact operation remains current.
• Carry the complete immutable accepted snapshot required by a graphical or direct projection host.
• Replace App's projection-visibility-derived entity event reconstruction.
• Preserve synchronous graphical projection application and exact retryable teardown acknowledgements.
• Do not emit on renderer rebucket, loaded/pending visibility, hydration retries, or other presentation-only changes.

5. Publish exact object-table commits

• Bind the stream to its owned ClientObjectTable.
• Convert callbacks to immutable RuntimeInventoryItemSnapshot values with generation metadata resolved by Runtime.
• Preserve add/update/move/remove/clear order and callback reentrancy.
• Keep optimistic movement and rollback synchronous.
• Ensure an authoritative delete produces the exact entity/object ordering pinned by J3.4.
• Do not add a second retained inventory collection.

6. Replace App entity/object view and event adapters

• Make CurrentGameRuntimeViewAdapter.Entities and .Inventory return the Runtime group's borrowed views.
• Remove its LiveEntityRuntime dependency for canonical entity/inventory reads.
• Make CurrentGameRuntimeEventAdapter forward the Runtime stream directly.
• Remove its ProjectionVisibilityChanged and object-table subscriptions.
• Retain command, lifecycle, chat, movement, and portal adapter work only until their scheduled J4–J6 owner moves.
• Add source guards preventing a new App entity/object mirror, sequencer, or owner-event reconstruction.

7. Direct/graphical parity and teardown

• Build one no-App Runtime fixture and one graphical-host fixture over the same input script.
• Compare normalized generation, sequence, identity, cell/state, properties, placement, and terminal edges exactly.
• Verify subscriber removal and Runtime disposal leave zero observers.
• Verify reset seals the old generation and a new session begins at sequence one without stale delivery.
• Verify graphical callbacks remain same-thread and press-time object reads remain immediate.

Adversarial cases

• Observer adds/removes an observer during dispatch.
• Observer creates, deletes, or replaces the same GUID reentrantly.
• Observer clears the session during create or object-table callbacks.
• Graphical projection callback throws after canonical commit.
• Same-incarnation CreateObject arrives while a prior projection teardown is retained.
• Authoritative delete races a dormant exact-incarnation record.
• Equal, stale, and wrapped timestamps.
• Local-ID wrap and namespace exhaustion.
• Graphical hydration fails before and after resource registration.
• Unknown-object move and removal.
• Container replacement mutates contents from inside an event callback.
• Multiple Runtime groups use identical GUIDs and session-generation values.
• Subscription disposal is replayed and Runtime disposal occurs during a callback.

Mandatory gates

Run in this order:

1. Runtime stream, borrowed-view, sequence, reentrancy, and identity tests.
2. Core ClientObjectTable* and ObjectTableWiring* tests.
3. Focused App Runtime-adapter, hydration, update, rebucket, deletion, reset, inventory, paperdoll, selection, interaction, and cooldown tests.
4. Direct-host versus graphical-host normalized parity fixture.
5. All Runtime tests.
6. All App tests.
7. dotnet build AcDream.slnx -c Release.
8. dotnet test AcDream.slnx -c Release --no-build.
9. Exact-binary connected lifecycle/reconnect gate.
10. At every connected checkpoint: zero render-shadow mismatches, zero pending deltas, graceful process exit, and exact canonical/projection teardown convergence.

A user visual pause is required only if an automated or connected gate exposes a visible inventory, selection, radar, paperdoll, or world-object symptom.

Acceptance

• Runtime owns one per-session ordered entity/object stream.
• Entity and inventory deltas share one generation/sequence order.
• Runtime views read the directory and object table directly.
• Every active canonical entity has a Runtime key before App projection.
• App reconstructs neither entity nor inventory events.
• Projection visibility is not emitted as canonical gameplay withdrawal.
• Graphical and no-window normalized traces are identical.
• No copied collection, queue, extra input frame, or backend dependency exists.
• Reentrant callbacks cannot resurrect or mutate a superseded incarnation.
• Reset/disposal leaves zero observers, queued deltas, and retained stream state.
• Complete Release and exact connected gates pass on one committed binary.

Rollback

J3.5 is independently reversible:

git revert ce3ac310d92722ffb637e81cb1957458874dd220

Do not revert J3.4 as a shortcut for a J3.5 failure. Automated and connected evidence is recorded in ../research/2026-07-26-slice-j3-5-canonical-delta-stream.md.

Next boundary

J3.6 executes from 2026-07-26-modern-runtime-slice-j3-hardening.md. It failure-injects the complete canonical entity/object lifecycle and proves zero records, tombstones, projections, resources, container entries, parent candidates, subscriptions, or pending deltas after reset and disposal. That closeout is required before J4 moves chat, inventory transactions, vitals, enchantments, spells/components, cooldowns, and ViewModel-facing revisions.