XCEngine/docs/plan/editor-windowing-runtime-boundary-refactor-plan.md

XCEditor Windowing Runtime Boundary Refactor Plan

Goal

Eliminate the last invalid architectural seam inside the editor windowing stack: Product/Core/Windowing/Contracts and Product/Core/Windowing/EditorWorkspaceShellRuntime were pretending to be reusable core abstractions, but they actually described concrete editor runtime services and a single concrete shell runtime flow.

The target state is:

• Product/Core/Windowing contains only stable value types and transfer models.
• Product/Runtime/Shell owns shell-definition and workspace-shell runtime services.
• Product/Runtime/Diagnostics owns frame-status and workspace trace services.
• windowing runtime code binds concrete runtime services directly instead of routing them through fake cross-layer contracts.

Root Problem

The previous structure had three coupled problems:

1. EditorShellDefinitionProvider, EditorFrameStatusService, and EditorFrameValidation were not true abstraction boundaries. They each had one editor-owned runtime implementation.
2. EditorWorkspaceShellRuntime was stored under Core, but its API was tied to editor runtime services, shell composition, viewport runtime wiring, and per-frame status synchronization.
3. These pseudo-contracts were threaded through constructor signatures and per-frame update contexts, so runtime-specific behavior leaked into supposedly reusable core types.

This made Core look reusable while actually encoding editor runtime policy.

Target Architecture

editor/src/Product/
  Core/
    Windowing/
      EditorShellVariant.h
      EditorWindowGeometry.h
      EditorWindowMetrics.h
      EditorWindowTransferRequests.h
      EditorWindowTypes.h
  Runtime/
    Diagnostics/
      EditorFrameStatusController.*
      WorkspaceTraceEntry.h
    Shell/
      EditorShellDefinitionService.*
      EditorShellRuntime.*
      EditorWorkspaceShellRuntime.h
    Windowing/
      Content/
      Frame/
      Runtime/
      Workspace/

Rules:

• Core/Windowing may only host stable primitive data, geometry, metrics, enums, and transfer request types.
• runtime services must live in Runtime/*, even when they are used widely.
• per-frame content contexts may carry frame data, but not service locators or fake contracts for globally owned runtime services.
• windowing runtime objects may depend directly on concrete editor runtime services when there is only one valid implementation.

Execution Stages

Stage 1 - Remove Fake Contracts

• Delete Product/Core/Windowing/Contracts/*.
• Delete Product/Core/Windowing/EditorFrameContracts.h.
• remove inheritance from runtime services that were only satisfying those fake contracts.

Exit condition:

• no editor runtime service inherits from Core/Windowing/Contracts

Status:

• completed

Stage 2 - Move Runtime Shell Ownership

• Move EditorWorkspaceShellRuntime out of Product/Core/Windowing into Product/Runtime/Shell.
• update all include paths to the runtime-owned shell boundary.

Exit condition:

• workspace shell runtime is owned only by Runtime/Shell

Status:

• completed

Stage 3 - Rewire Windowing Runtime To Concrete Services

• bind EditorShellDefinitionService and EditorFrameStatusController directly in EditorShellRuntime
• bind the same concrete services directly in EditorWindowRuntimeController and EditorWindowManager
• remove shellDefinitionProvider and frameStatusService from EditorWindowContentFrameContext
• stop passing shell-definition and frame-status pseudo-services through per-frame window update calls

Exit condition:

• the frame loop no longer depends on fake contracts or contract-style service passing

Status:

• completed

Stage 4 - Physical Cleanup And Audit

• remove the empty Core/Windowing/Contracts directory
• search for all old type names and include paths
• rebuild XCEditor
• run the required 12-second smoke test

Exit condition:

• no code references the removed contract layer
• XCEditor builds
• smoke test exits cleanly

Status:

• completed

Validation

Validated on 2026-04-30:

• cmake --build build --config Debug --target XCEditor
• smoke test: XCUIEDITOR_SMOKE_TEST=1 XCUIEDITOR_SMOKE_TEST_DURATION_SECONDS=12

Observed result:

• build succeeded
• smoke process exited with EXIT_CODE=0
• measured smoke duration was 14.22 seconds

Final State

The root architectural issue is closed when all of the following are true:

1. Product/Core/Windowing contains only stable value-layer windowing types.
2. no Contracts directory exists under Product/Core/Windowing.
3. EditorWorkspaceShellRuntime is runtime-owned, not core-owned.
4. frame status and shell definition services are concrete runtime services, not pseudo-interfaces.
5. windowing frame code no longer forwards fake contract services per frame.
6. build and smoke validation both pass.

Current status:

• all six conditions are satisfied

Marker Audit

No .dog files are present in the workspace as of the final audit on 2026-04-30, so there is no remaining marker file to remove for this refactor.