72 lines
3.1 KiB
Markdown
72 lines
3.1 KiB
Markdown
# PR-26 Walker Cache Input and Comparison Policy
|
|
|
|
Domain Owner: `docs/packer`
|
|
|
|
## Briefing
|
|
|
|
Once the durable cache model exists, the next narrow step is to let walkers consume prior cached file facts without coupling them to cache storage.
|
|
|
|
This PR defines the cache-aware walker contract and the ordered invalidation policy that decides when prior metadata can be reused and when a fresh probe is mandatory.
|
|
|
|
## Objective
|
|
|
|
Deliver walker-side prior-cache input and a deterministic comparison policy ordered by `size`, then newer `lastModified`, then fingerprint/hash.
|
|
|
|
## 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)
|
|
|
|
## Scope
|
|
|
|
- extend walker inputs so they receive prior asset cache state
|
|
- keep walkers independent from cache repository I/O
|
|
- apply walker-side internal file analysis only to already-registered assets
|
|
- define ordered invalidation checks:
|
|
- changed `size` invalidates immediately
|
|
- newer `lastModified` invalidates immediately
|
|
- fingerprint/hash is evaluated last when stronger confirmation is still needed
|
|
- allow walkers to reuse prior metadata when cached facts remain valid
|
|
- preserve file-scoped diagnostics in walk output
|
|
|
|
## Non-Goals
|
|
|
|
- no runtime snapshot attachment yet
|
|
- no cache persistence integration in the loader yet
|
|
- no point write-path refresh yet
|
|
- no Studio UI contract changes
|
|
|
|
## Execution Method
|
|
|
|
1. Update walker contracts to accept prior asset cache input together with asset root and declaration.
|
|
2. Keep cache lookup outside concrete walkers; they should receive an already-resolved asset cache view.
|
|
3. Implement the ordered invalidation policy in the shared walker path.
|
|
4. Reuse prior metadata only when the ordered checks keep the cached entry valid.
|
|
5. Preserve file-scoped diagnostics in the resulting walk output for later runtime and UI consumption.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- walkers receive prior asset cache entries as input
|
|
- the walker layer does not perform cache repository I/O directly
|
|
- unregistered assets are excluded from internal file analysis and cache-aware walker reuse
|
|
- changed `size` invalidates prior reuse immediately
|
|
- newer `lastModified` invalidates prior reuse immediately
|
|
- fingerprint/hash remains the final expensive comparison step
|
|
- stable files may reuse prior metadata without changing query-visible semantics
|
|
- file-scoped diagnostics remain segregated in walk output
|
|
|
|
## Validation
|
|
|
|
- walker tests proving changed `size` invalidates reuse
|
|
- walker tests proving newer `lastModified` invalidates reuse
|
|
- walker tests proving fingerprint/hash is only evaluated after cheaper checks do not already invalidate reuse
|
|
- walker tests proving stable files can reuse prior metadata
|
|
- tests proving file-scoped diagnostics remain attached to per-file walk output
|
|
|
|
## Affected Artifacts
|
|
|
|
- `docs/packer/pull-requests/**`
|
|
- `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/test/java/p/packer/repositories/**`
|