packer (WIP)
This commit is contained in:
parent
67edeaab78
commit
77516e9f3c
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -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`
|
||||
|
||||
@ -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`
|
||||
|
||||
@ -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<byte[]>` 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`
|
||||
|
||||
@ -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/<operation-id>/`.
|
||||
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`
|
||||
|
||||
@ -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`
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user