prometeu-studio/docs/packer/pull-requests/PR-27-runtime-walkresult-and-cache-integration.md

PR-27 Runtime WalkResult and Cache Integration

Domain Owner: docs/packer Cross-Domain Impact: docs/studio

Briefing

With cache persistence and walker reuse policy isolated, the final slice is to connect them to the runtime model.

This PR makes the runtime loader hydrate prior cache before the walk, attach the current walkResult to the in-memory snapshot, sink general diagnostics into the normal diagnostics surface, preserve file-scoped diagnostics for UI consumers, and refresh the durable cache from the cacheable portions of the current walk.

Objective

Deliver runtime-side integration of prior cache hydration, walkResult snapshot attachment, diagnostics sink split, and refreshed cache persistence.

Dependencies

• ./PR-24-asset-file-cache-hydration-and-walker-reuse.md
• ./PR-25-asset-cache-model-and-repository.md
• ./PR-26-walker-cache-input-and-comparison-policy.md
• ./PR-15-snapshot-backed-asset-query-services.md
• ./PR-21-point-in-memory-snapshot-updates-after-write-commit.md
• ../specs/5. Diagnostics, Operations, and Studio Integration Specification.md

Scope

• load prior cache.json during runtime snapshot bootstrap and refresh
• resolve prior cache by asset_id before invoking the walker
• attach a byte-free runtime projection of the current walkResult to the in-memory runtime asset model
• retain enough walk data in the runtime snapshot to inspect available files, build-candidate files, and bank-size measurement data
• avoid retaining raw file bytes for the full discovered file set in the runtime snapshot
• sink general walk diagnostics into the normal asset/runtime diagnostics surface
• preserve file-scoped diagnostics as segregated walk output for UI consumers
• refresh and persist cache from the cacheable portions of the current walk
• support point cache refresh for one affected asset after successful write commit and re-walk

Non-Goals

• no new Studio feature surface beyond exposing already-owned file-scoped walk data
• no background reconcile observer
• no build/incremental pipeline work

Execution Method

1. Load prior workspace cache at runtime bootstrap and on refresh.
2. Resolve the current asset cache slice by asset_id and pass it into the walker. Assets without asset_id are outside this flow and should not receive internal file analysis or cache ownership.
3. Attach a dedicated runtime projection of the current walkResult to the runtime snapshot model. The first implementation should keep the available file set, the build-candidate subset, and bank-size measurement data accessible from the snapshot instead of optimizing that shape away early. The runtime projection should drop raw file bytes and should not retain raw PackerFileProbe objects unless a narrower later use case proves they are needed.
4. Route general walk diagnostics into the standard asset/runtime diagnostics sink.
5. Preserve file-scoped diagnostics inside the walk result projection used by later query/UI consumers.
6. Persist refreshed cache after coherent runtime load completes.
7. Reuse the same logic to refresh one asset cache slice after successful point write commit and re-walk.

Acceptance Criteria

• runtime load reads prior cache before invoking walkers
• cache lookup passed to the walker is aligned by asset_id
• assets without asset_id are excluded from cache ownership and internal file analysis
• runtime assets retain a byte-free projection of the current walk output in memory
• runtime assets retain enough walk data to inspect available files, build-candidate files, and bank-size measurement data
• runtime snapshot retention excludes raw file bytes for the general discovered file set
• general walk diagnostics appear in the normal diagnostics surface
• file-scoped diagnostics remain segregated for detailed consumers
• refreshed cache written after runtime load contains only cacheable probe facts and metadata
• point write flows can refresh only one affected asset cache entry after commit
• missing, malformed, or incompatible cache falls back to cold walk without blocking runtime queries

Validation

• loader tests for cold load without cache
• loader tests for warm load with cache hydration
• snapshot/query tests proving walkResult is attached to runtime assets
• diagnostics tests proving general sink aggregation and file-scoped segregation
• cache refresh tests proving the durable artifact is rebuilt from cacheable walk data only
• runtime registry tests for one-asset cache refresh after point write commit

Affected Artifacts

• docs/packer/pull-requests/**
• docs/packer/specs/5. Diagnostics, Operations, and Studio Integration Specification.md
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/**
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/**
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/**
• prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/**
• prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/**
• prometeu-studio/** query adapter coverage when file-scoped diagnostics become consumable