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, 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
• 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
• 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.