prometeu-studio/docs/packer/pull-requests/PR-34-tile-bank-diagnostics-and-validation-hardening.md

PR-34 Tile Bank Diagnostics and Validation Hardening

Domain Owner: docs/packer Cross-Domain Impact: docs/studio

Briefing

The tile-bank decision closed the structural blockers and warnings that must exist before pack emission.

Those diagnostics belong in the walker/materialization path so they surface during validation and are naturally rerun by packWorkspace(...) when a fresh frozen snapshot is created.

This PR isolates that diagnostic work from payload emission.

Objective

Add the accepted tile-bank diagnostics to the packer walk/materialization path and make validation consume them consistently.

Dependencies

• ../decisions/Tile Bank Packing Materialization Decision.md
• ../decisions/Pack Wizard Pack Execution Semantics Decision.md
• PR-33 for normative spec propagation

Scope

• add tile-bank structural blocking diagnostics
• add tile-bank warning diagnostics for fragile indices
• ensure those diagnostics live in the walker/materialization path
• ensure validation consumes them without special late pack-only logic

Non-Goals

• no full payload emission yet
• no staging/promote pipeline yet
• no shipper behavior
• no future multi-tile-per-artifact support

Method

1. Add blocking diagnostics for:
   • duplicate artifacts[*].index
   • gaps in normalized artifact indices
   • fixed-sheet capacity overflow
   • banks without declared palettes
   • palette declaration count above 64
   • malformed palette declarations
   • missing or invalid required tile-bank metadata
   • failures to normalize artifacts into deterministic tile candidates
2. Add WARNING diagnostics for fragile tile indices across the full declared bank palette set.
3. Ensure diagnostics are attached at file/asset walk time so:
   • GetAssetDetails
   • ValidatePackWorkspace
   • future pack rerun gate all see the same structural findings.
4. Add tests that distinguish blocking failures from advisory warnings.

Acceptance Criteria

• validation returns blocked tile-bank assets when any accepted blocker exists
• fragile-index findings are visible but do not block by themselves
• no tile-bank structural problem is discovered only during final byte emission
• the same diagnostic vocabulary is visible in details and validation paths

Validation

• targeted service and walker tests
• validation-flow regression tests
• asset-details regression tests for warning and blocking surfaces

Affected Artifacts

• prometeu-packer-v1 tile-bank walker/materialization code
• prometeu-packer-v1 validation/query services
• related tests under prometeu-packer-v1/src/test