76 lines
2.7 KiB
Markdown
76 lines
2.7 KiB
Markdown
# 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/Tile%20Bank%20Packing%20Materialization%20Decision.md)
|
|
- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.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`
|
|
|