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

```text
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.