prometeu-runtime/discussion/workflow/plans/PLN-0015-api-bank-integration-and-tests.md

id	ticket	title	status	created	completed	tags
PLN-0015	scene-bank-and-viewport-cache-refactor	Plan - API, Bank Integration, and Tests	accepted	2026-04-13		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
• 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
• 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
• crates/console/prometeu-drivers/src/memory_banks.rs
• 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.