---
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, final integration surfaces, 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. `PLN-0011` already removed the old canonical tile-layer APIs and introduced `BankType::SCENE` plus scene-aware bank slots. The binary `SCENE` payload contract and decoder are now isolated in `PLN-0016`.

## Scope

### Included
- Update bridge APIs and exposed runtime surfaces.
- 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:**
- Verify `GfxBridge` and adjacent bridge traits stay free of obsolete canonical layer ownership assumptions after cache/resolver integration.
- 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 the pre-`SceneBank` model.

**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 - Remove stale type and API remnants

**What:**
Clean out old interfaces that would leave the codebase in a dual-model state.

**How:**
- Remove any remaining obsolete references to:
  - `TileLayer`
  - `ScrollableTileLayer`
  - direct old-layer scroll ownership APIs
  - transitional commented fallback paths left during migration
- 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 4 - 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.
- [ ] Stale old-layer APIs are removed.
- [ ] Full-stack regression coverage exists for the migration.

## Dependencies

- Depends on `PLN-0011`, `PLN-0012`, `PLN-0013`, `PLN-0014`, and `PLN-0016`.
- Source decision: `DEC-0013`

## Risks

- API cleanup is where hidden dependencies on the old model are most likely to surface.
- If stale APIs are not removed aggressively, the codebase can get stuck in a fragile dual-model transition.