acdream/docs/plans/2026-07-26-modern-runtime-slice-j6.md

Modern runtime Slice J6 — world, transit, and host handshake

Status: J6.0–J6.3 COMPLETE; J6.4 ACTIVE Parent: 2026-07-25-modern-runtime-slice-j.md, J6
Authorization: the user approved Slices F–L, including gameplay-owner moves, on 2026-07-24
Purpose: move the one authoritative world-environment and local-transit lifetime into AcDream.Runtime while preserving the accepted retail portal presentation and leaving graphical readiness, streaming, sky drawing, VFX, audio, and UI in AcDream.App.

1. Retail ordering oracle

The load and placement boundary is fixed by the named retail client:

• SmartBox::TeleportPlayer @ 0x00453910
• SmartBox::UseTime @ 0x00455410
• gmSmartBoxUI::EndTeleportAnimation @ 0x004D65A0
• CPhysicsObj::enter_world @ 0x00516170
• SkyDesc::CalcPresentDayGroup @ 0x00500E10
• CPlayerSystem::Handle_Admin__Environs @ 0x0055DE20

The consolidated pseudocode is already captured in:

• docs/research/2026-07-15-retail-portal-space-pseudocode.md
• docs/research/2026-07-16-portal-completion-pseudocode.md
• docs/research/2026-07-24-retail-streaming-retirement-pseudocode.md
• docs/research/2026-04-23-daygroup-selection.md

The load-bearing order is:

fresh F751 notification
    establish one teleport generation
matching accepted Position
    establish one exact destination
CellManager finishes destination load
    host acknowledges exact generation + destination readiness
SmartBox::TeleportPlayer / CPhysicsObj::enter_world
    commit position and destination cell
    resume destination simulation
gmSmartBoxUI::EndTeleportAnimation
    continue private tunnel presentation
TunnelFadeOut -> WorldFadeIn
    reveal normal world viewport
WorldFadeIn tail ends
    send LoginComplete and complete the generation

The graphical host may delay the readiness acknowledgement until render, composite-texture, and collision publication have converged. It does not own the teleport generation, destination identity, materialization state, or simulation availability. A headless host supplies the same acknowledgement contract using its own required domains.

2. Current owner inventory

2.1 Authoritative state incorrectly retained in App

Current owner	State	J6 destination
WorldEnvironmentController	server-synced world clock, selected day group, weather, AdminEnvirons override, debug overrides	RuntimeWorldEnvironmentState
static DerethDateTime.OriginOffsetTicks	mutable Region calendar origin shared by every process session	instance DerethCalendar owned by each environment
TeleportTransitCoordinator<T>	F751 freshness, Position correlation, accepted-destination history	RuntimeWorldTransitState
WorldRevealLifecycleTelemetry	reveal generation, destination, readiness, materialized/completed/cancelled/world-visible state	RuntimeWorldTransitState
WorldGenerationAvailabilityState	whether gameplay/world simulation may advance	borrowed projection of RuntimeWorldTransitState
CurrentGameRuntimeViewAdapter.PortalView	reconstructs Runtime portal state from App lifecycle state	direct borrowed Runtime view

2.2 App state that must remain App

Owner	Reason
WorldRevealReadinessBarrier	joins renderer, texture-upload, and collision-publication facts
StreamingController / destination reservation	graphical streaming and publication
WorldRevealRenderResourceScheduler	GPU upload priority
PortalTunnelPresentation, TeleportAnimSequencer, TeleportViewPlaneController	private graphical presentation
WorldGenerationQuiescence effects	clears graphical selection and suspends/resumes world audio
LoadedSkyDesc / DayGroupData projection	raw DAT-backed sky presentation and renderer input
terrain, EnvCell, sky, VFX, audio, UI owners	presentation

2.3 State that already has the correct Runtime owner

• Current player full-cell and position: RuntimeLocalPlayerMovementState.
• Accepted entity position/timestamp state: RuntimeEntityDirectory.
• Canonical entity identity and incarnation: RuntimeEntityObjectLifetime.
• Physics placement/cell membership: RuntimePhysicsState.
• Network session generation and ordered transport: LiveSessionController.

J6 must borrow these owners. It may not add a second current-cell field, entity map, movement body, session generation, or packet queue.

3. Target Runtime contracts

3.1 Environment

public sealed class RuntimeWorldEnvironmentState
{
    WorldTimeService WorldTime { get; }
    WeatherSystem Weather { get; }
    RuntimeWorldEnvironmentSnapshot Snapshot { get; }

    void Initialize(RuntimeWorldEnvironmentDefinition definition);
    void SynchronizeFromServer(double ticks);
    RuntimeEnvironmentEffect ApplyAdminEnvirons(uint changeType);
    void RefreshDayGroup();
    void ResetSession();
}

The immutable definition contains only presentation-independent values: calendar origin, sky tick rate, and ordered day-group descriptors with the Core SkyStateProvider. Runtime owns the selected index and weather state. App retains the raw LoadedSkyDesc and resolves Runtime's active index to the matching DayGroupData for drawing.

WorldTimeService receives an instance DerethCalendar and an injectable TimeProvider; production no longer mutates process-global calendar origin or reads wall time through a hidden static dependency.

3.2 Transit/reveal

public readonly record struct RuntimeTeleportDestination(...);

public readonly record struct RuntimeDestinationReadiness(
    long Generation,
    uint DestinationCell,
    bool IsUnhydratable,
    bool RenderReady,
    bool CompositeReady,
    bool CollisionReady);

public sealed class RuntimeWorldTransitState : IRuntimePortalView
{
    bool QueueTeleportStart(ushort sequence);
    RuntimeDestinationOfferResult OfferDestination(...);
    bool ActivatePending(out RuntimeTeleportDestination destination);

    long BeginReveal(RuntimePortalKind kind, uint destinationCell);
    bool AcknowledgeDestinationReadiness(in RuntimeDestinationReadiness ack);
    bool AcknowledgeMaterialized(long generation, uint destinationCell);
    bool AcknowledgeWorldViewportVisible(long generation);
    bool Complete(long generation);
    bool Cancel(long generation);
    void ResetSession();
}

All mutators validate the exact active generation and destination. A stale acknowledgement cannot open a newer destination. Readiness is an immutable host acknowledgement; Runtime owns the resulting lifecycle state.

The snapshot separately exposes:

• destination readiness;
• simulation availability;
• materialization;
• normal-world viewport observation;
• completion/cancellation.

This preserves retail's two release edges:

1. materialization resumes destination simulation;
2. the later tunnel/world swap releases graphical destination reservations.

3.3 App adapters

WorldRevealCoordinator becomes a graphical host adapter:

• it asks Runtime to begin the generation;
• begins exact-generation streaming and render-resource reservations;
• evaluates App readiness and acknowledges the exact generation/cell;
• projects Runtime simulation-availability edges to selection/audio;
• releases graphical reservations only at the viewport edge;
• owns no lifecycle snapshot or generation counter.

LocalPlayerTeleportController remains the portal presentation orchestrator. It borrows RuntimeWorldTransitState for F751/Position correlation and lifecycle facts, while retaining only translated render-space placement, camera/view-plane state, tunnel animation, and App callback reentrancy guards.

4. Execution ledger

J6.0 — owner proof and detailed plan

• Re-read the named retail functions and existing consolidated pseudocode.
• Inventory every producer, consumer, reset edge, and checkpoint.
• Pin the target contracts, no-mirror rules, sub-slices, gates, and rollback discipline in this document.

Gate: documentation/source audit proves every mutable field has exactly one planned owner and no accepted presentation edge changes.

J6.1 — instance-scoped environment owner

Complete 2026-07-26 at 902076c0.

• Add DerethCalendar and make WorldTimeService consume its exact instance.
• Add RuntimeWorldEnvironmentState and immutable environment definitions.
• Reduce App's WorldEnvironmentController to DAT conversion plus IWorldSceneSkyStateSource projection.
• Route TimeSync, AdminEnvirons, diagnostics, render weather, and sky lookup through the one Runtime state.
• Delete production mutation of DerethDateTime.OriginOffsetTicks.
• Add two-instance isolation, day-group equality, TimeSync, debug override, AdminEnvirons, reset, and teardown tests.

Gate: Core/Runtime/App focused tests, Release build, full tests, exact day-group fixtures, and no Runtime dependency violation.

Result: Runtime now owns the one instance-scoped calendar, synchronized world clock, weather state, selected day group, AdminEnvirons state, and debug overrides. App only translates immutable DAT sky definitions and projects the selected Runtime state into the renderer. The 332 Runtime tests, 3,718 App tests / 3 skips, 8,611 complete Release tests / 5 skips, and exact-binary connected lifecycle/reconnect route pass. Both connected clients used 902076c0a42079596a8a273e9be402776cabf4b0, completed all seven checkpoints, and exited gracefully with code zero. Evidence: ../research/2026-07-26-slice-j6-1-environment-ownership.md.

J6.2 — canonical reveal generation and typed readiness

Complete 2026-07-26 at a6860d55 plus connected correction acb845d8.

• Add RuntimeWorldTransitState, immutable readiness acknowledgement, and direct IRuntimePortalView.
• Move lifecycle telemetry and generation state from App to Runtime.
• Make WorldRevealCoordinator a strict App host adapter.
• Replace App's mutable availability state with a read-only Runtime projection; retain selection/audio side effects as exact edge observers.
• Reject stale generation, wrong destination, reordered, duplicate, and post-cancel acknowledgements.
• Preserve unhydratable destination behavior and the five-second retail wait cue without a timeout or forced reveal.

Gate: login, portal, supersession, stale acknowledgement, callback failure, session reset, and exact two-release-edge fixtures pass.

Result: Runtime owns the sole monotonic reveal generation, destination, typed readiness latch, materialization/simulation edge, viewport observation, completion, cancellation, wait cue, and portal materialization count. App's former lifecycle owner is deleted; WorldRevealCoordinator is a graphical host adapter and WorldGenerationAvailabilityState is a read-only Runtime projection. The first connected run correctly exposed that post-acceptance render-readiness samples may regress while the accepted atomic edge must remain latched; acb845d8 ignores those later samples without mutating Runtime truth or reporting false invariant failures.

Runtime tests pass 349/349, App tests pass 3,716/3 skips, and the complete Release suite passes 8,626/5 skips. Exact-binary report logs/connected-world-gate-20260726-171724/report.json records six capped checkpoints and one uncapped fresh-process reconnect, graceful code-zero exits, zero failures, zero reveal invariant failures, and only the expected world-edge warning. Evidence: ../research/2026-07-26-slice-j6-2-reveal-ownership.md.

J6.3 — canonical F751/Position transit and placement handshake

Complete 2026-07-26 at 6a063a27.

• Move TeleportTransitCoordinator state into the Runtime transit owner.
• Convert accepted network destination data once into RuntimeTeleportDestination.
• Keep render-space translation/recenter and camera placement in App.
• Validate placement and materialization against the exact Runtime generation, sequence, and destination cell.
• Derive current session cell from the existing Runtime movement/entity owner; add no parallel current-cell field.
• Reset/cancel transit through Runtime's structural teardown.
• Delete the App transit coordinator and App portal-view reconstruction.

Gate: Position-before-F751, F751-before-Position, duplicate/stale/wrapped sequence, superseding teleport, same-landblock, cross-landblock, dungeon, mid-portal reset, and reconnect traces match.

RuntimeWorldTransitState now owns wrap-safe F751 history, pending/active teleport sequence, both accepted packet orders, the exact destination, and generation/sequence/cell placement and materialization validation. The former App transit coordinator and accepted-destination mirror are deleted; App retains only graphical portal and placement work.

Runtime tests pass 360/360, the focused App transit/reveal suite passes 34/34, App tests pass 3,710/3 skips, and the complete Release suite passes 8,631/5 skips. Exact-binary report logs/connected-world-gate-20260726-175333/report.json records six capped checkpoints and one uncapped fresh-process reconnect, graceful code-zero exits, zero failures, zero reveal invariant failures, and only the expected world-edge warning. Evidence: ../research/2026-07-26-slice-j6-3-teleport-correlation.md.

J6.4 — projection acknowledgement and owner cleanup

• Make App presentation registration/withdrawal use typed generation-scoped acknowledgements.
• Ensure simulation release, viewport reveal, reservation release, and final completion each occur once and retain retryable suffixes after a callback failure.
• Remove superseded App lifecycle/generation state and compatibility types.
• Extend normalized checkpoints and ownership ledgers with environment, transit, readiness, and pending-host-ack counts.
• Add direct/no-window host fixtures proving Runtime can complete login, portal, cancellation, and reset without loading App or a backend.

Gate: source/dependency guards find no App authority or Runtime presentation dependency; every failure-injection ledger converges to zero.

J6.5 — connected and documentation closeout

• Run focused Core, Runtime, and App projects.
• Run dotnet build AcDream.slnx -c Release.
• Run the complete Release test suite.
• Rebuild the exact binary.
• Run fresh login, repeated recall/portal, world edge, dungeon, graceful disconnect, reconnect, and mid-portal disconnect routes.
• Compare the accepted portal screenshots and presentation trace.
• Update architecture, code structure, milestone, roadmap, parent plan, AGENTS/CLAUDE, divergence ledger, and durable memory.

J6 is complete only when automated and connected evidence proves:

• one Runtime environment owner;
• one Runtime transit/reveal owner;
• no stale destination acknowledgement can reveal a different generation;
• no App portal-state reconstruction remains;
• no portal timing, paperdoll, object-lifetime, VFX-tail, or world-void regression;
• teardown and reconnect converge with no pending host acknowledgement.

5. Mandatory adversarial matrix

• two Runtime instances with different Region origins and server clocks;
• TimeSync while a debug override is active;
• day/year rollover and day-group reselection;
• every AdminEnvirons fog and sound value, plus unknown values;
• Position before F751 and F751 before Position;
• duplicate, old, equal, and ushort-wrapped teleport sequences;
• readiness for the wrong generation or destination;
• ready then superseded, materialized then cancelled, viewport ack before readiness, and duplicate completion;
• destination recenter still pending;
• indoor render ready without EnvCell collision;
• outdoor collision ready without the full render neighborhood;
• unhydratable authoritative destination;
• callback reentrancy at begin, readiness, placement, viewport, and complete;
• disconnect during every portal animation state;
• same-process disconnect/reconnect and two simultaneous Runtime instances;
• graphical host withdrawal failure followed by retry;
• zero App/UI/Silk/OpenAL/Arch assemblies in direct Runtime tests.

6. Commit and rollback discipline

Each coherent production sub-slice lands separately after its focused, Release, full-suite, dependency, and teardown gates. The exact production commit and matching git revert <sha> are recorded here, in the parent plan, the closeout evidence, architecture, and durable memory before moving on.

J6.1 exact rollback:

git revert 902076c0a42079596a8a273e9be402776cabf4b0

J6.2 exact rollback, newest first:

git revert acb845d812574206da1693fb379fec8a6f175fcb
git revert a6860d5563ae845a2cbb916abacf2b4aee515cdb

J6.3 exact rollback:

git revert 6a063a27d4c805cd166d5a487afc290c34c400fd

Documentation-only research/plan commits are not behavior rollback points. No workaround, timer, forced-ready path, duplicated owner, or alternate headless behavior is permitted.