prometeu-studio/docs/packer/pull-requests/PR-35-packing-aware-walkers-and-runtime-materialization-preparation.md

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/Tile Bank Packing Materialization Decision.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