89 lines
5.4 KiB
Markdown
89 lines
5.4 KiB
Markdown
# 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-24-asset-file-cache-hydration-and-walker-reuse.md)
|
|
- [`./PR-25-asset-cache-model-and-repository.md`](./PR-25-asset-cache-model-and-repository.md)
|
|
- [`./PR-26-walker-cache-input-and-comparison-policy.md`](./PR-26-walker-cache-input-and-comparison-policy.md)
|
|
- [`./PR-15-snapshot-backed-asset-query-services.md`](./PR-15-snapshot-backed-asset-query-services.md)
|
|
- [`./PR-21-point-in-memory-snapshot-updates-after-write-commit.md`](./PR-21-point-in-memory-snapshot-updates-after-write-commit.md)
|
|
- [`../specs/5. Diagnostics, Operations, and Studio Integration Specification.md`](../specs/5.%20Diagnostics,%20Operations,%20and%20Studio%20Integration%20Specification.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
|