implements PLN-0011

This commit is contained in:
2026-04-13 20:13:16 +01:00
parent 70cde0d975
commit e1afc164ae
22 changed files with 1905 additions and 348 deletions
@@ -0,0 +1,152 @@
---
id: PLN-0011
ticket: scene-bank-and-viewport-cache-refactor
title: Plan - Scene Core Types and Bank Contract
status: accepted
created: 2026-04-13
completed:
tags: [gfx, tilemap, runtime, render]
---
## Objective
Introduce the canonical type model required by `DEC-0013`: `SceneBank`, `SceneLayer`, `TileMap`, and `Tile`, plus the asset-bank/domain contract changes needed to carry scene-backed tilemap data as the new source of truth.
## Background
`DEC-0013` locks the canonical runtime model around `SceneBank` and `SceneLayer`, replacing the old `TileLayer`/`ScrollableTileLayer` coupling. This plan isolates the domain-model and bank-contract refactor before cache or renderer migration begins.
## Scope
### Included
- Introduce `SceneBank` and `SceneLayer` in the HAL/runtime model.
- Preserve `TileMap` and `Tile` as canonical grid/unit concepts.
- Define the minimum `SceneLayer` fields required by the decision.
- Update bank/domain enums and payload contracts so scenes can exist as first-class banked content.
- Add compile-time migration shims only when strictly needed to keep the tree buildable during the refactor.
### Excluded
- `SceneViewportCache`
- `SceneViewportResolver`
- renderer migration to cache consumption
- rematerialization algorithm
- final composition changes
- final binary `SCENE` payload format and decoder implementation
## Execution Steps
### Step 1 - Introduce canonical scene types in HAL
**What:**
Add `SceneBank` and `SceneLayer` to the HAL model and define the minimum canonical fields required by the decision.
**How:**
- Replace or retire the old `TileLayer`-centric model in [tile_layer.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/tile_layer.rs).
- Keep `TileMap` as the canonical grid owner and `Tile` as the canonical cell unit.
- Define `SceneLayer` with:
- `glyph_bank_id`
- `tile_size`
- `active`
- `motion_factor`
- `tilemap`
- Define `SceneBank` as the aggregate of exactly four `SceneLayer`s using a fixed array.
**File(s):**
- [crates/console/prometeu-hal/src/tile_layer.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/tile_layer.rs)
- [crates/console/prometeu-hal/src/tile.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/tile.rs)
- [crates/console/prometeu-hal/src/glyph.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/glyph.rs)
- HAL module export files as needed
### Step 2 - Remove `ScrollableTileLayer` from the canonical model
**What:**
Delete the canonical role of `ScrollableTileLayer` and any direct ownership path that makes scroll part of the canonical scene representation.
**How:**
- Remove `ScrollableTileLayer` and `HudTileLayer` from the HAL tile-layer model or reduce them to non-canonical transitional wrappers only if needed to keep compilation moving during the refactor.
- Ensure canonical scene state no longer encodes direct renderer scroll ownership.
**File(s):**
- [crates/console/prometeu-hal/src/tile_layer.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/tile_layer.rs)
- [crates/console/prometeu-hal/src/gfx_bridge.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/gfx_bridge.rs)
### Step 3 - Introduce the bank/domain contract for scene-backed content
**What:**
Add or revise the asset-bank/domain model so the canonical loaded scene can be represented in the bank contract.
**How:**
- Update `BankType` and related asset/bank metadata in HAL to support `Scene`-backed content at the domain level.
- Adjust slot/reference types where necessary so scene content can be addressed consistently with existing banks.
- Keep the exact asset-bank enum wiring minimal and domain-first; do not conflate it with renderer cache details.
**File(s):**
- [crates/console/prometeu-hal/src/asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/asset.rs)
- [crates/console/prometeu-hal/src/syscalls/domains/bank.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/syscalls/domains/bank.rs)
- [crates/console/prometeu-hal/src/syscalls/domains/asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/syscalls/domains/asset.rs)
- Any bank-facing shared types used by runtime and drivers
### Step 4 - Thread the new scene types through driver-facing runtime structures
**What:**
Prepare the driver layer to reference canonical `SceneBank` types instead of old layer/map ownership.
**How:**
- Identify the driver-side structs currently owning the old layer model.
- Replace those type references with the new canonical scene types without yet switching renderer logic to the viewport cache.
- Keep this step focused on compile-safe type replacement, not behavior changes.
**File(s):**
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)
- [crates/console/prometeu-drivers/src/hardware.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/hardware.rs)
### Step 5 - Add baseline tests for the canonical scene model
**What:**
Protect the new canonical scene types with focused tests before cache and renderer work begins.
**How:**
- Add unit tests for:
- scene-bank construction
- layer ownership of tilemaps
- tile write/read behavior
- preservation of `motion_factor`
- Keep tests domain-focused and independent of viewport caching.
**File(s):**
- HAL tests colocated with scene/tile modules
- Driver tests only if required to preserve build integrity
## Test Requirements
### Unit Tests
- `SceneBank` owns exactly four canonical `SceneLayer`s.
- `SceneLayer` exposes the required minimal fields.
- `TileMap` indexing and mutation still behave canonically.
- `motion_factor` survives construction and mutation paths.
### Integration Tests
- Asset/bank domain types accept the new scene-backed contract without breaking existing glyph/sound usage.
- `SCENE` binary decode remains intentionally open and out of scope for this plan.
### Manual Verification
- Build the console crates and verify no canonical runtime path still treats `ScrollableTileLayer` as the source of truth.
## Acceptance Criteria
- [ ] `SceneBank` and `SceneLayer` exist as canonical runtime types.
- [ ] `ScrollableTileLayer` is no longer the canonical scene model.
- [ ] Bank/domain types can represent scene-backed content.
- [ ] Driver-facing runtime structures compile against the new canonical scene model.
- [ ] Baseline tests protect the new type graph.
## Dependencies
- Source decision: `DEC-0013`
- No dependency on later plans; this is the foundation for the rest of the family.
## Risks
- Breaking too many public or cross-crate type references at once can stall compilation.
- Bank enum changes can ripple into syscalls and telemetry if not scoped carefully.
- Transitional wrappers can accidentally survive longer than intended if not explicitly retired in later plans.
@@ -0,0 +1,147 @@
---
id: PLN-0012
ticket: scene-bank-and-viewport-cache-refactor
title: Plan - Scene Viewport Cache Structure
status: accepted
created: 2026-04-13
completed:
tags: [gfx, tilemap, runtime, render]
---
## Objective
Implement the `SceneViewportCache` as the operational render cache for one `Scene`, including one internal ringbuffer per layer and lightweight derived cache entries for raster acceleration.
## Background
`DEC-0013` locks `SceneViewportCache` as the renderer-facing view of scene data and prefers internal ringbuffer storage per layer. This plan isolates the cache data structure and update API before resolver and renderer integration.
## Scope
### Included
- Define `SceneViewportCache`.
- Define the per-layer internal ringbuffer structure.
- Define the cached tile entry format.
- Define cache update APIs for line, column, and area/region.
- Define full invalidation on scene swap.
### Excluded
- camera logic
- drift/hysteresis logic
- final renderer migration
- execution of blits into `back`
## Execution Steps
### Step 1 - Define cache entry and layer-cache structures
**What:**
Create the internal data model for one viewport cache layer and for cached tile entries.
**How:**
- Introduce a cache tile entry type that stores:
- resolved `glyph_id`
- resolved `palette_id`
- packed flip flags
- `active/empty`
- fast layer-local glyph bank reference/index
- Introduce one ringbuffer-backed layer-cache structure per scene layer.
- Keep ringbuffer internals encapsulated and out of public semantic APIs.
**File(s):**
- New HAL or driver-side viewport-cache module(s), likely under:
- `crates/console/prometeu-hal/src/`
- and/or `crates/console/prometeu-drivers/src/`
### Step 2 - Define `SceneViewportCache` as a four-layer aggregate
**What:**
Create the top-level cache aggregate for one `Scene`.
**How:**
- Represent one cache aggregate containing four internal layer caches.
- Thread through cache dimensions and tile-size assumptions for V1.
- Make the cache explicitly scene-derived and non-canonical.
**File(s):**
- New cache module(s)
- Any related exports in HAL/driver public surfaces
### Step 3 - Implement cache mutation APIs
**What:**
Define the update surface that later plans will use for rematerialization.
**How:**
- Add explicit APIs for:
- refresh line
- refresh column
- refresh area/region
- invalidate whole cache on scene swap
- Ensure corner refresh can use region updates without duplicate work on already-present tiles.
**File(s):**
- New cache module(s)
- Any helper modules shared with resolver integration
### Step 4 - Implement scene-to-cache materialization helpers
**What:**
Add helpers that copy canonical scene data into cache entries.
**How:**
- Build helpers that read canonical `SceneLayer`/`TileMap` data and populate cache entries.
- Keep the helpers unaware of camera policy; they should only perform requested materialization work.
- Ensure per-layer movement factors remain metadata of the scene layer, not cache-only state.
**File(s):**
- New cache/materialization helper module(s)
### Step 5 - Add focused tests for cache structure and update rules
**What:**
Protect the cache shape and update operations before wiring the resolver.
**How:**
- Add tests for:
- ringbuffer wrap behavior
- line refresh
- column refresh
- region refresh
- scene-swap invalidation
- no duplicate reload for corner-style region updates
**File(s):**
- Tests colocated with cache modules
## Test Requirements
### Unit Tests
- Each cache layer maintains ringbuffer invariants under wrap.
- Cache entry fields match the expected derived values from canonical scene tiles.
- Line/column/region refresh APIs only rewrite the requested area.
### Integration Tests
- Materialization from `Scene` into `SceneViewportCache` succeeds across all four layers.
### Manual Verification
- Inspect debug output or temporary probes to confirm cache updates do not expose ringbuffer details outside the cache boundary.
## Acceptance Criteria
- [ ] `SceneViewportCache` exists as a four-layer aggregate.
- [ ] Each layer cache uses internal ringbuffer storage.
- [ ] Cache entries store the lightweight derived raster fields defined by the decision.
- [ ] Explicit APIs exist for line, column, area/region, and full invalidation.
- [ ] Tests cover wrap and non-duplicative corner updates.
## Dependencies
- Depends on `PLN-0011` for canonical `Scene` / `SceneLayer` / `TileMap` types.
- Source decision: `DEC-0013`
## Risks
- Over-designing cache entry shape can accidentally turn the cache into a second heavy scene representation.
- Ringbuffer implementation bugs can stay hidden until resolver integration if tests are too weak.
- Region refresh semantics can become ambiguous if API boundaries are not explicit early.
@@ -0,0 +1,161 @@
---
id: PLN-0013
ticket: scene-bank-and-viewport-cache-refactor
title: Plan - Scene Viewport Resolver and Rematerialization
status: accepted
created: 2026-04-13
completed:
tags: [gfx, tilemap, runtime, render]
---
## Objective
Implement `SceneViewportResolver` as the owner of master totem, per-layer totems, drift, hysteresis, clamp, cache update decisions, and per-layer copy instrumentation metadata.
## Background
`DEC-0013` makes the resolver the owner of movement policy between camera input and viewport cache updates. This plan isolates the decision logic before final renderer migration.
## Scope
### Included
- Define `SceneViewportResolver`.
- Implement master totem and per-layer derived totems.
- Implement drift and hysteresis.
- Implement clamp behavior.
- Implement cache-update triggering and copy instrumentation metadata.
### Excluded
- actual framebuffer copy execution
- sprite/HUD/fade composition logic
- broad renderer migration
## Execution Steps
### Step 1 - Define resolver state and inputs
**What:**
Create the resolver state model and its public input surface.
**How:**
- Define resolver state to own:
- master totem
- per-layer derived totems
- viewport dimensions
- hysteresis thresholds
- clamp-relevant scene bounds
- Define the external entry point that accepts camera position input.
**File(s):**
- New resolver module(s), likely under HAL or drivers depending on final ownership
### Step 2 - Implement master-to-layer totem derivation
**What:**
Make layer motion derive from the master totem using each layer’s `totem_factor`.
**How:**
- Compute per-layer effective motion from the master totem.
- Preserve support for normal layers (`1.0`) and parallax/background-like layers (`!= 1.0`).
- Keep the derivation explicit and testable per axis.
**File(s):**
- Resolver module(s)
- Any math/helper module(s) needed for factor handling
### Step 3 - Implement drift, hysteresis, and clamp
**What:**
Translate camera motion into discrete totem advancement safely.
**How:**
- Implement drift calculation in pixel space against totem centers in tile space.
- Implement hysteresis with:
- internal safe band
- external trigger band
- Implement clamp against scene bounds.
- Ensure edge behavior is explicitly asymmetric when clamped.
**File(s):**
- Resolver module(s)
### Step 4 - Connect resolver decisions to cache update requests
**What:**
Turn resolver state changes into concrete cache update requests.
**How:**
- Emit requests for:
- line refresh
- column refresh
- area/region refresh for corner updates
- Ensure no duplicate work is scheduled for already-covered cache content.
- Keep the resolver in charge of “what to refresh,” not “how cache storage performs it.”
**File(s):**
- Resolver module(s)
- Shared request/command structs between resolver and cache
### Step 5 - Add copy instrumentation outputs for later renderer use
**What:**
Make the resolver capable of describing which cache slice/region should be copied for each layer.
**How:**
- Define a per-layer copy request/instrumentation type.
- Include enough information for a later compositor to copy from cache into `back` without re-deciding viewport math.
- Do not execute the copy here.
**File(s):**
- Resolver module(s)
- Shared copy-request types
### Step 6 - Add focused resolver tests
**What:**
Protect resolver correctness before renderer integration.
**How:**
- Add tests for:
- master totem updates
- per-layer totem factor derivation
- hysteresis stability
- repeated high-speed movement
- clamp at scene edges
- corner-trigger conversion into region refresh requests
**File(s):**
- Tests colocated with resolver modules
## Test Requirements
### Unit Tests
- Hysteresis prevents edge flick/thrash.
- Totem movement occurs discretely in tile steps.
- Per-layer totems follow the master according to `totem_factor`.
- Clamp behavior is correct near scene edges.
### Integration Tests
- Resolver outputs valid update requests consumable by `SceneViewportCache`.
### Manual Verification
- Instrument logs or debug traces to confirm no unnecessary refresh churn during back-and-forth movement near edges.
## Acceptance Criteria
- [ ] `SceneViewportResolver` exists with the full state required by `DEC-0013`.
- [ ] Master and per-layer totems are derived correctly.
- [ ] Hysteresis and clamp are implemented and tested.
- [ ] Cache refresh requests are emitted by line, column, and region as required.
- [ ] Copy instrumentation metadata is available for later renderer use.
## Dependencies
- Depends on `PLN-0011` and `PLN-0012`.
- Source decision: `DEC-0013`
## Risks
- Resolver logic can become hard to reason about if movement, clamp, and copy instrumentation are not clearly separated.
- Parallax factor derivation can introduce subtle off-by-one or drift mismatch issues per layer.
- Region-update scheduling can duplicate work if X/Y corner movement is not normalized carefully.
@@ -0,0 +1,142 @@
---
id: PLN-0014
ticket: scene-bank-and-viewport-cache-refactor
title: Plan - Renderer Migration to Scene Viewport Cache
status: accepted
created: 2026-04-13
completed:
tags: [gfx, tilemap, runtime, render]
---
## Objective
Migrate world rendering from direct canonical map consumption to `SceneViewportCache` consumption while preserving the accepted observable composition order.
## Background
`DEC-0013` makes `SceneViewportCache` the immediate source of copy data for world blits and preserves the visible order of world layers, interleaved sprites, and HUD. This plan focuses on the renderer migration itself.
## Scope
### Included
- Remove direct world-layer map reads from the renderer hot path.
- Make world-layer composition consume cache-backed copy requests.
- Preserve sprite interleaving and HUD ordering.
- Keep V1 destructive `back` composition acceptable.
### Excluded
- scene domain model refactor
- cache structural implementation
- resolver movement logic
- non-world rendering systems beyond required integration points
## Execution Steps
### Step 1 - Identify and isolate direct canonical map consumption in the renderer
**What:**
Locate current renderer paths that read canonical layer maps directly.
**How:**
- Replace direct `TileMap` reads in [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs) with abstraction points prepared to accept cache-sourced copy requests.
- Keep the migration incremental enough to preserve buildability.
**File(s):**
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)
### Step 2 - Introduce world-layer copy paths driven by cache requests
**What:**
Teach the renderer to copy world content from `SceneViewportCache`.
**How:**
- Add renderer-facing entry points that consume per-layer copy instrumentation emitted by the resolver.
- Ensure the renderer treats the cache as the immediate world source for blit operations.
- Do not let the renderer re-own totem/drift/clamp policy.
**File(s):**
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)
- Supporting cache/resolver integration modules
### Step 3 - Preserve accepted composition order
**What:**
Keep the visible ordering of layers, sprites, and HUD intact during migration.
**How:**
- Preserve composition order:
- world layer 0
- sprites
- world layer 1
- sprites
- world layer 2
- sprites
- world layer 3
- sprites
- HUD
- Keep `HUD`, sprites, and fades outside the viewport-cache invalidation model.
**File(s):**
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)
### Step 4 - Preserve destructive `back` composition for V1
**What:**
Accept destructive composition while still benefiting from cache-backed world inputs.
**How:**
- Keep the first migrated renderer implementation destructive in `back`.
- Ensure the code path clearly separates:
- canonical scene data
- viewport cache data
- final composition buffer
- Avoid mixing “cache update” with “final buffer copy” concerns in the renderer.
**File(s):**
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)
### Step 5 - Add renderer regression coverage
**What:**
Protect the migrated composition order and world rendering behavior.
**How:**
- Add tests or golden-style checks for:
- world layers rendered from cache, not canonical maps
- visible ordering of sprites between layers
- HUD remaining on top
- Add probes or assertions preventing accidental fallback to direct canonical map reads.
**File(s):**
- Renderer tests in [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs) and adjacent test modules
## Test Requirements
### Unit Tests
- Cache-driven world copy code produces the same visible layer ordering as the prior renderer.
### Integration Tests
- Full `render_all()` path uses `SceneViewportCache` for world layers.
- Sprites/HUD/fades remain correctly ordered relative to world layers.
### Manual Verification
- Render representative scenes with multiple active layers and sprites to confirm no visible ordering regressions.
## Acceptance Criteria
- [ ] Renderer world composition no longer reads canonical scene maps directly in the hot path.
- [ ] World layers are copied from `SceneViewportCache`.
- [ ] Sprite interleaving and HUD ordering remain correct.
- [ ] V1 destructive composition still works end-to-end.
- [ ] Regression coverage protects the migrated path.
## Dependencies
- Depends on `PLN-0011`, `PLN-0012`, and `PLN-0013`.
- Source decision: `DEC-0013`
## Risks
- Renderer migration can accidentally duplicate world-copy work if cache and compositor responsibilities blur.
- Sprite ordering regressions are easy to introduce during world-layer refactoring.
- Temporary fallback paths can linger unless tests explicitly block them.
@@ -0,0 +1,141 @@
---
id: PLN-0015
ticket: scene-bank-and-viewport-cache-refactor
title: Plan - API, Bank Integration, and Tests
status: accepted
created: 2026-04-13
completed:
tags: [gfx, tilemap, runtime, render]
---
## Objective
Finish the scene/viewport-cache migration by aligning exposed APIs, bank-loading integration, and test coverage across HAL, drivers, and system entry points.
## Background
After core types, cache, resolver, and renderer migration exist, the remaining work is to align the surrounding surfaces so the new architecture is usable as the runtime’s operational model.
## Scope
### Included
- Update bridge APIs and exposed runtime surfaces.
- Align bank-loading/integration paths with scene-backed content.
- Remove stale tile-layer-era interfaces.
- Add cross-layer regression coverage.
### Excluded
- additional architectural redesign
- feature work beyond the accepted decision
## Execution Steps
### Step 1 - Update HAL and bridge surfaces
**What:**
Remove or replace public APIs still shaped around the old scrollable tile-layer model.
**How:**
- Update `GfxBridge` and adjacent bridge traits so they no longer expose obsolete canonical layer ownership assumptions.
- Introduce scene/cache/resolver-oriented access only where required by runtime consumers.
**File(s):**
- [crates/console/prometeu-hal/src/gfx_bridge.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/gfx_bridge.rs)
- Other bridge traits affected by scene model changes
### Step 2 - Align driver/hardware construction paths
**What:**
Ensure hardware and driver initialization paths can construct and own the new scene/cache/resolver model.
**How:**
- Update hardware bootstrap and driver ownership paths to instantiate the canonical scene and viewport-cache stack.
- Remove any remaining ownership assumptions tied to `ScrollableTileLayer`.
**File(s):**
- [crates/console/prometeu-drivers/src/hardware.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/hardware.rs)
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)
### Step 3 - Align asset/bank integration paths
**What:**
Make sure bank-loading and asset integration paths understand the scene-backed model at the operational layer.
**How:**
- Update asset-side or loader-side integration points so scene-backed content can be staged, installed, and referenced coherently.
- Keep the work scoped to the bank-loading path; do not reopen the canonical model here.
**File(s):**
- [crates/console/prometeu-drivers/src/asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs)
- [crates/console/prometeu-drivers/src/memory_banks.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/memory_banks.rs)
- [crates/console/prometeu-hal/src/cartridge_loader.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/cartridge_loader.rs)
- Related asset/bank shared types
### Step 4 - Remove stale type and API remnants
**What:**
Clean out old interfaces that would leave the codebase in a dual-model state.
**How:**
- Remove obsolete references to:
- `TileLayer`
- `ScrollableTileLayer`
- direct old-layer scroll ownership APIs
- Keep only the canonical scene model and the viewport-cache/render pipeline required by the decision.
**File(s):**
- HAL and driver modules touched by earlier plans
### Step 5 - Add full-stack regression coverage
**What:**
Add the minimum test family needed to execute the migration safely one plan at a time.
**How:**
- Add tests for:
- canonical scene ownership
- viewport-cache update behavior
- resolver drift/hysteresis
- renderer composition order
- scene swap invalidation
- absence of stale old-layer APIs
- Add at least one integration path that exercises:
- scene load
- cache population
- resolver update
- renderer world composition
**File(s):**
- Test modules across HAL, drivers, and system crates as needed
## Test Requirements
### Unit Tests
- Public/runtime-facing APIs no longer depend on `ScrollableTileLayer`.
- Cache, resolver, and renderer modules remain individually covered.
### Integration Tests
- End-to-end scene load -> cache update -> renderer composition path succeeds.
- Scene swap invalidates cache and repopulates correctly.
### Manual Verification
- Build the runtime and exercise representative world scenes to confirm no stale assumptions remain in construction or render flow.
## Acceptance Criteria
- [ ] Bridge and runtime-facing APIs align with the new scene/cache model.
- [ ] Hardware/driver construction paths instantiate the new architecture correctly.
- [ ] Asset/bank integration paths accept the scene-backed model.
- [ ] Stale old-layer APIs are removed.
- [ ] Full-stack regression coverage exists for the migration.
## Dependencies
- Depends on `PLN-0011`, `PLN-0012`, `PLN-0013`, and `PLN-0014`.
- Source decision: `DEC-0013`
## Risks
- API cleanup is where hidden dependencies on the old model are most likely to surface.
- Asset/bank integration can expand in scope if loader assumptions are too tightly coupled to current bank enums.
- If stale APIs are not removed aggressively, the codebase can get stuck in a fragile dual-model transition.