Internal Viewport 270p (480x270)

discussion/lessons/DSC-0030-internal-viewport-270p/LSN-0039-resolution-baseline-changes-are-runtime-wide-contracts.md

@@ -0,0 +1,72 @@
+---
+id: LSN-0039
+ticket: internal-viewport-270p
+title: Resolution Baseline Changes Are Runtime-Wide Contracts, Not Host-Only Resizes
+created: 2026-04-28
+tags: [gfx, runtime, viewport, resolution, frame-composer, host, docs]
+---
+
+## Context
+
+`DSC-0030` changed Prometeu's canonical internal viewport from `320x180` to `480x270`. The important outcome was not just a larger host window or sharper scaling. The accepted contract changed what the console shows per frame, which forced coordinated propagation through runtime constants, frame composition, host presentation, pointer mapping, tests, stress fixtures, and published specs.
+
+The work only became truly complete after specs and touch semantics were updated to match executable reality. Until that final publication step, the discussion was still operationally open even though most code paths had already migrated.
+
+## Key Decisions
+
+### Resolution Baseline Is a Console Contract
+
+**What:**
+`480x270` became the single canonical runtime framebuffer and viewport baseline for Prometeu.
+
+**Why:**
+Treating resolution as a host presentation detail would preserve the old framing and miss the product-level intent. The migration was explicitly about showing more world per frame, so the contract had to move at the runtime level.
+
+**Trade-offs:**
+This increases framebuffer, cache, and copy-path cost. It also makes partial migrations dangerous because old assumptions can survive in tests, tools, and docs even after the main runtime constants change.
+
+### Propagation Must Follow Ownership Boundaries
+
+**What:**
+The migration propagated through the systems that actually own the contract:
+- runtime constants and `FrameComposer` viewport behavior;
+- host framebuffer creation and absolute touch mapping;
+- tests and stress cartridges that encode visible-domain assumptions;
+- public specs for graphics and touch semantics.
+
+**Why:**
+Viewport changes cross subsystem boundaries, but each subsystem should update only the part it owns. That keeps the migration coherent without re-opening unrelated architecture.
+
+**Trade-offs:**
+The work naturally splits into several execution slices. That adds coordination overhead, but it prevents one oversized patch from mixing runtime behavior, host presentation, and documentation cleanup without a clear boundary.
+
+### Housekeeping Should Wait for the Last Contract Publication Step
+
+**What:**
+The discussion was only ready for cleanup after the docs slice closed and no public spec still described `320x180` as canonical.
+
+**Why:**
+A finished implementation with stale published contract text is still incomplete from the repository's point of view. Housekeeping should reflect published truth, not just mostly-finished code.
+
+**Trade-offs:**
+This keeps discussions open slightly longer, but it avoids archiving a thread before the normative contract is actually consistent everywhere it is published.
+
+## Patterns and Algorithms
+
+- Treat viewport or resolution changes as contract migrations, not cosmetic host tweaks.
+- Split propagation by ownership: runtime, host/tests, then specs/docs.
+- Rebase stress fixtures and generated cartridges when they encode screen-domain assumptions.
+- Use one canonical source of resolution truth in code and make docs follow only after executable migration is complete.
+
+## Pitfalls
+
+- Updating only the host surface can look successful while silently preserving the wrong gameplay framing.
+- Test fixtures and generated artifacts often keep old screen bounds longer than production code.
+- Documentation can lag behind implementation and keep the discussion operationally open even when code seems done.
+
+## Takeaways
+
+- Internal resolution is part of the console contract and must be migrated runtime-wide.
+- A framing change is not equivalent to a presentation-scale change.
+- Specs and generated stress assets are part of closing the contract, not optional cleanup.
+- Housekeeping should happen only after code, tests, tooling, and published docs agree on the same baseline.