Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity

packer (WIP)

Browse Source
This commit is contained in:
bQUARKz 2026-03-20 09:36:48 +00:00
parent 67edeaab78
commit 77516e9f3c
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
5 changed files with 320 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
docs/packer/pull-requests/PR-33-tile-bank-spec-propagation-and-runtime-contract-alignment.md Normal file
View File

@ -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`

75
docs/packer/pull-requests/PR-34-tile-bank-diagnostics-and-validation-hardening.md Normal file
View File

@ -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`

69
docs/packer/pull-requests/PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md Normal file
View File

@ -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`

86
docs/packer/pull-requests/PR-36-pack-workspace-execution-with-frozen-snapshot-and-staging.md Normal file
View File

@ -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`

11
docs/packer/pull-requests/README.md
View File

@ -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) 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) 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) 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: Current wave discipline from `PR-11` onward:
@ -97,4 +106,4 @@ Current wave discipline from `PR-11` onward:
Recommended dependency chain: 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`