diff --git a/docs/packer/pull-requests/PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md b/docs/packer/pull-requests/PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md new file mode 100644 index 00000000..1d8927c4 --- /dev/null +++ b/docs/packer/pull-requests/PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md @@ -0,0 +1,80 @@ +# PR-33 Tile Bank Spec Propagation and Runtime Contract Alignment + +Domain Owner: `docs/packer` +Cross-Domain Impact: `../runtime`, `docs/studio` + +## Briefing + +The `Tile Bank Packing Materialization Decision` is now closed. + +Before more code lands, the normative spec path needs to be updated so implementation is not forced to infer format details from agendas and decisions. + +This PR is editorial-first. +Its job is to propagate the accepted tile-bank producer contract into the relevant packer specs and to make the runtime alignment explicit. + +## Objective + +Update the normative spec corpus so `tile bank` v1 packing has one unambiguous producer contract. + +## 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) +- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md) +- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md) + +## Scope + +- propagate the accepted `tile bank` v1 contract into packer specs +- define canonical payload semantics for `TILES/indexed_v1` +- define metadata convergence shape for tile-bank runtime entries +- make runtime-aligned size and decoded-size formulas explicit +- document the fixed `256 x 256` target and row-major slot semantics + +## Non-Goals + +- no production code changes +- no walker refactor +- no payload emitter implementation +- no runtime implementation work + +## Method + +1. Update [`../specs/4. Build Artifacts and Deterministic Packing Specification.md`](../specs/4.%20Build%20Artifacts%20and%20Deterministic%20Packing%20Specification.md). +2. Define `TILES/indexed_v1` producer semantics explicitly: + - `1 artifact = 1 tile` + - `tile_id = normalized artifacts[*].index` + - fixed `256 x 256` emitted sheet + - row-major placement + - packed `u4` pixel plane + - `64 * 16 * u16` RGB565 palette block +3. Document runtime entry derivation: + - `bank_type = TILES` + - `codec = NONE` + - `size = ceil(width * height / 2) + 2048` + - `decoded_size = (width * height) + 2048` +4. Document metadata normalization: + - `output.metadata -> metadata` + - `output.codec_configuration -> metadata.codec` + - `output.pipeline -> metadata.pipeline` +5. Cross-reference the runtime-side metadata normalization discussion without pretending it is already closed there. + +## Acceptance Criteria + +- the packer spec corpus contains one explicit producer contract for tile-bank v1 +- the payload shape no longer needs to be reconstructed from agenda text +- size, decoded-size, palette count, and metadata shape are all normative +- the spec states what the producer emits because that is what the consumer requires + +## Validation + +- editorial review against the accepted decision +- consistency check against runtime specs and loader assumptions +- terminology review for `tile_id`, `palette_id`, `size`, `decoded_size`, and metadata segmentation + +## Affected Artifacts + +- `docs/packer/specs/4. Build Artifacts and Deterministic Packing Specification.md` +- possibly `docs/packer/specs/1. Domain and Artifact Boundary Specification.md` +- possibly `docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md` + diff --git a/docs/packer/pull-requests/PR-34-tile-bank-diagnostics-and-validation-hardening.md b/docs/packer/pull-requests/PR-34-tile-bank-diagnostics-and-validation-hardening.md new file mode 100644 index 00000000..104762e5 --- /dev/null +++ b/docs/packer/pull-requests/PR-34-tile-bank-diagnostics-and-validation-hardening.md @@ -0,0 +1,75 @@ +# 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` + diff --git a/docs/packer/pull-requests/PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md b/docs/packer/pull-requests/PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md new file mode 100644 index 00000000..0932f57d --- /dev/null +++ b/docs/packer/pull-requests/PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md @@ -0,0 +1,69 @@ +# PR-35 Packing-Aware Walkers and Runtime Materialization Preparation + +Domain Owner: `docs/packer` +Cross-Domain Impact: `docs/studio` + +## Briefing + +Pack execution now depends on a frozen in-memory execution snapshot, but the repository deliberately chose not to fork discovery into one runtime walker stack and one packing walker stack. + +This PR prepares the existing walker/materialization path so it can serve both runtime reads and pack execution with explicit policy. + +## Objective + +Prepare walkers and runtime materialization for packing-aware projection without implementing final pack emission yet. + +## Dependencies + +- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md) +- [`../decisions/Tile Bank Packing Materialization Decision.md`](../decisions/Tile%20Bank%20Packing%20Materialization%20Decision.md) +- `PR-34` for diagnostics already present in the walk/materialization path + +## Scope + +- add optional content bytes to runtime walk projection +- introduce or finish the accepted materialization config/policy shape +- keep family walkers discovery-oriented +- enable packing-focused projection filtering over discovered probes +- make build-relevant content bytes available for packing snapshots only + +## Non-Goals + +- no final `packWorkspace(...)` implementation yet +- no staging/promotion yet +- no tile-bank payload bytes emitted yet +- no alternative walker stack + +## Method + +1. Add `Optional` support to `PackerRuntimeWalkFile`. +2. Ensure full probes can still carry bytes internally during discovery. +3. Materialize runtime projection using explicit config/policy: + - runtime mode suppresses optional bytes + - packing mode injects optional bytes + - projection filter keeps only build-relevant selected probes +4. Keep family walkers focused on relevance-by-family. +5. Add tests showing: + - runtime default projection does not retain bytes + - packing projection retains bytes only for relevant selected files + - the same discovery path serves both modes + +## Acceptance Criteria + +- the repository has one walker discovery path, not two divergent ones +- packing projection can freeze build-relevant bytes in memory +- runtime-backed reads do not become wasteful full-memory mirrors +- selected build inputs survive into runtime walk projection with optional bytes when packing mode is requested + +## Validation + +- targeted runtime materialization tests +- walker reuse regression tests +- cache integration review where relevant + +## Affected Artifacts + +- `prometeu-packer-v1` walker models +- `prometeu-packer-v1` runtime materializer/export path +- related tests under `prometeu-packer-v1/src/test` + diff --git a/docs/packer/pull-requests/PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md b/docs/packer/pull-requests/PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md new file mode 100644 index 00000000..9bfe5333 --- /dev/null +++ b/docs/packer/pull-requests/PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md @@ -0,0 +1,86 @@ +# PR-36 Pack Workspace Execution with Frozen Snapshot and Staging + +Domain Owner: `docs/packer` +Cross-Domain Impact: `docs/studio`, `../runtime` + +## Briefing + +After specs, diagnostics, and packing-aware materialization are in place, the remaining step is the actual pack execution pipeline. + +This PR implements `packWorkspace(...)` as the first end-to-end writer that: + +- reruns the gate on a fresh execution snapshot; +- materializes build outputs from frozen in-memory inputs; +- stages outputs before promotion; +- and publishes coherent final artifacts to `build/`. + +## Objective + +Implement the first-wave `packWorkspace(...)` pipeline with frozen snapshot input, tile-bank payload emission, and staged publication. + +## Dependencies + +- [`../decisions/Pack Wizard Pack Execution Semantics Decision.md`](../decisions/Pack%20Wizard%20Pack%20Execution%20Semantics%20Decision.md) +- [`../decisions/Tile Bank Packing Materialization Decision.md`](../decisions/Tile%20Bank%20Packing%20Materialization%20Decision.md) +- `PR-33` +- `PR-34` +- `PR-35` + +## Scope + +- implement pack rerun gate on a fresh execution snapshot +- materialize tile-bank payload bytes from frozen in-memory inputs +- emit `assets.pa` and companion outputs in staging +- promote staged outputs into final `build/` locations only on coherent success +- return structured pack results for blocked, failed, and successful outcomes + +## Non-Goals + +- no shipper packaging or `.pbc` generation +- no remote or incremental build behavior +- no cancellation semantics +- no non-tile-bank payload families unless they are already trivial and fully decided + +## Method + +1. Create a fresh frozen execution snapshot for the current included-in-build set. +2. Rerun the pack validation gate on that snapshot before byte emission begins. +3. For tile banks: + - normalize selected artifacts into one row-major `256 x 256` sheet + - pack tile pixels as `u4` + - emit the `64 * 16 * 2` RGB565 palette block + - derive runtime entry metadata using the accepted segmentation contract +4. Emit staged outputs under `build/.staging//`. +5. Promote staged outputs into: + - `build/assets.pa` + - `build/asset_table.json` + - `build/preload.json` + - `build/asset_table_metadata.json` +6. Return structured terminal results that distinguish: + - gate failure + - execution/materialization failure + - persistence/promotion failure + +## Acceptance Criteria + +- `packWorkspace(...)` never emits from live filesystem rereads after frozen snapshot creation +- gate rerun blocks stale-invalid projects even if validation was green earlier +- failed execution before promotion does not leave partial final build outputs visible as success +- successful execution publishes coherent final build outputs +- tile-bank payload bytes satisfy the accepted producer contract and runtime consumer assumptions + +## Validation + +- targeted `packWorkspace(...)` service tests +- tile-bank conformance tests from artifacts to emitted payload +- staging/promotion failure-path tests +- regression tests for blocked vs failed vs successful results + +## Affected Artifacts + +- `prometeu-packer-api` pack result contract +- `prometeu-packer-v1` pack execution service +- `prometeu-packer-v1` tile-bank payload materializer +- `prometeu-packer-v1` staging/promote pipeline +- related tests under `prometeu-packer-v1/src/test` + diff --git a/docs/packer/pull-requests/README.md b/docs/packer/pull-requests/README.md index 2afafe04..cee9da53 100644 --- a/docs/packer/pull-requests/README.md +++ b/docs/packer/pull-requests/README.md @@ -87,6 +87,15 @@ The current production track for the standalone `prometeu-packer` project is: 25. [`PR-25-asset-cache-model-and-repository.md`](./PR-25-asset-cache-model-and-repository.md) 26. [`PR-26-walker-cache-input-and-comparison-policy.md`](./PR-26-walker-cache-input-and-comparison-policy.md) 27. [`PR-27-runtime-walkresult-and-cache-integration.md`](./PR-27-runtime-walkresult-and-cache-integration.md) +28. [`PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md`](./PR-28-pack-wizard-public-contracts-summary-validation-and-execution.md) +29. [`PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md`](./PR-29-pack-wizard-contract-adjustments-for-summary-and-validation.md) +30. [`PR-30-pack-wizard-summary-snapshot-query.md`](./PR-30-pack-wizard-summary-snapshot-query.md) +31. [`PR-31-pack-wizard-validation-snapshot-gate.md`](./PR-31-pack-wizard-validation-snapshot-gate.md) +32. [`PR-32-palette-declarations-with-explicit-index-contract.md`](./PR-32-palette-declarations-with-explicit-index-contract.md) +33. [`PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md`](./PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md) +34. [`PR-34-tile-bank-diagnostics-and-validation-hardening.md`](./PR-34-tile-bank-diagnostics-and-validation-hardening.md) +35. [`PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md`](./PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md) +36. [`PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md`](./PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md) Current wave discipline from `PR-11` onward: @@ -97,4 +106,4 @@ Current wave discipline from `PR-11` onward: Recommended dependency chain: -`PR-01 -> PR-02 -> PR-03 -> PR-04 -> PR-05 -> PR-06 -> PR-07 -> PR-08 -> PR-09 -> PR-10 -> PR-11 -> PR-12 -> PR-13 -> PR-14 -> PR-15 -> PR-16 -> PR-17 -> PR-18 -> PR-19 -> PR-20 -> PR-21 -> PR-22 -> PR-23 -> PR-24 -> PR-25 -> PR-26 -> PR-27` +`PR-01 -> PR-02 -> PR-03 -> PR-04 -> PR-05 -> PR-06 -> PR-07 -> PR-08 -> PR-09 -> PR-10 -> PR-11 -> PR-12 -> PR-13 -> PR-14 -> PR-15 -> PR-16 -> PR-17 -> PR-18 -> PR-19 -> PR-20 -> PR-21 -> PR-22 -> PR-23 -> PR-24 -> PR-25 -> PR-26 -> PR-27 -> PR-28 -> PR-29 -> PR-30 -> PR-31 -> PR-32 -> PR-33 -> PR-34 -> PR-35 -> PR-36`