prometeu-studio/docs/packer/pull-requests/PR-25-asset-cache-model-and-repository.md

PR-25 Asset Cache Model and Repository

Domain Owner: docs/packer

Briefing

PR-24 defines the need for a durable asset file cache in assets/.prometeu/cache.json, but the first executable slice should stop at cache persistence itself.

Before walkers or runtime snapshot integration can reuse prior file facts safely, the packer needs a stable cache schema, explicit load/save ownership, and tests that prove the cache is keyed correctly and excludes non-cacheable data.

Objective

Deliver the durable cache.json model and repository, keyed by stable asset_id, with no persisted diagnostics.

Dependencies

• ./PR-24-asset-file-cache-hydration-and-walker-reuse.md
• ./PR-14-project-runtime-core-snapshot-model-and-lifecycle.md
• ../specs/2. Workspace, Registry, and Asset Identity Specification.md

Scope

• define the durable schema for assets/.prometeu/cache.json
• key asset cache ownership by stable asset_id
• omit unregistered assets from durable cache ownership entirely
• key file cache entries by normalized relative path inside the asset root
• persist reusable probe facts only:
  • mimeType
  • size
  • lastModified
  • fingerprint/hash
  • family-specific metadata
• exclude diagnostics from the durable cache artifact
• add a packer-owned repository for cache load/save and schema validation

Non-Goals

• no walker contract changes yet
• no cache comparison or reuse policy yet
• no runtime snapshot model changes yet
• no Studio adapter changes

Execution Method

1. Add cache model types under the packer runtime model layer.
2. Define one versioned workspace cache artifact for assets/.prometeu/cache.json.
3. Encode asset entries by asset_id, never by asset root path.
4. Encode file entries by normalized asset-relative path.
5. Add repository load/save behavior with safe fallback on missing or invalid cache files.
6. Prove by tests that diagnostics cannot be serialized into the durable cache artifact.

Acceptance Criteria

• the packer has explicit model types for the durable cache artifact
• cache ownership is keyed by asset_id
• unregistered assets do not receive durable cache entries
• file cache entries are keyed by normalized relative file path
• repository load on absent cache returns a safe empty state
• malformed or schema-incompatible cache can be rejected cleanly without crashing the runtime load path
• diagnostics are not part of the serialized cache schema

Validation

• schema serialization tests for workspace cache
• repository round-trip tests for valid cache content
• repository tests for absent cache file
• repository tests for malformed cache file
• cache model tests proving asset_id-aligned lookup
• serialization tests proving diagnostics are excluded from cache.json

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/**