content-hash-cache

name	content-hash-cache
description	Add content-addressed caching to expensive file processing workflows such as PDF parsing, OCR, image analysis, document extraction, generated asset rendering, or batch transforms. Use when repeated processing should be skipped safely even if file paths change.

Content Hash Cache

Use this skill when a workflow repeatedly processes files and the result depends on file bytes rather than the file path.

Fit Check

Use a content-hash cache when:

• processing is expensive enough to matter;
• identical file bytes should reuse the same result;
• moved or renamed files should still hit the cache;
• changed file content should automatically miss;
• cached output can be serialized safely.

Do not use it when output depends on current time, live network state, user permissions, external mutable databases, or hidden process state unless those inputs are also included in the cache key.

Cache Key

Build the key from:

sha256(file bytes) + processor version + relevant options

Include processor version or options when changing extraction mode, OCR language, model, prompt, page range, resolution, or output schema changes the result.

Recommended Layout

.cache/<workflow-name>/
  entries/
    <cache-key>.json
  tmp/
  README optional only if humans need it

Each entry should include:

• source hash;
• source path for debugging only;
• processor name and version;
• options hash or normalized options;
• created timestamp;
• serialized result;
• optional warning list.

Workflow

1. Normalize options into a stable object.
2. Compute the file content hash in chunks.
3. Combine content hash, processor version, and options hash.
4. Look for an entry by key.
5. On hit, validate minimal entry metadata before returning it.
6. On miss, run the pure processor.
7. Write the cache entry atomically via a temporary file and rename.
8. Log hit, miss, bypass, and corrupt-entry events with short hashes.

Design Rules

• Keep the expensive processor pure: it should not know about cache storage.
• Wrap caching in a service layer.
• Treat unreadable or corrupt cache entries as misses.
• Do not cache secrets unless the cache directory is explicitly protected and the result is safe to persist.
• Provide a --no-cache or equivalent bypass for debugging.
• Provide a cache version bump when result shape changes.

Validation

Test these cases:

• same file same options hits;
• same bytes under a different filename hits;
• changed bytes miss;
• changed options miss;
• corrupt JSON entry misses and reprocesses;
• cache bypass reprocesses.

Acceptance: cache behavior is deterministic, path-independent, and explainable in logs.