Cache retention: CacheBackend introspection + `cache ls` + last-accessed marker

#14 · open · 0 comments

View on GitHub ↗

no0dles

## What to build Give the `CacheBackend` interface the introspection needed for retention, and surface it via `hammerkit cache ls`. Extend the backend to enumerate entries with `taskId`, `stateKey`, `size`, `createdAt`, and `lastAccessedAt` (where the backend can supply them). Because filesystem `atime` is unreliable (relatime/noatime), maintain a **hammerkit-owned last-accessed marker** updated on each cache hit (`pull`) — a small sidecar per entry — rather than relying on OS atime. `hammerkit cache ls` lists each entry with its task id, state key, size, and last-accessed time. A backend that cannot report a field reports the unsupported policy as unavailable rather than silently doing nothing. Output routes through the `Environment` (no `console.*`). This is the foundation the `cache prune` slice builds on (entry enumeration + the LRU marker). The local backend stores entries as `<taskId>/<stateKey>/` directories with `stats.json` written last; enumeration and size come from walking that layout, and the marker is a sidecar in each entry directory. References: `specs/cache-retention/spec.md` (US3 FR-001, FR-003, FR-009, FR-010). ## Acceptance criteria - [ ] The `CacheBackend` interface exposes entry enumeration (taskId, stateKey, size, createdAt, lastAccessedAt where supplied). - [ ] A cache hit (`pull`) updates a hammerkit-owned last-accessed marker; OS atime is not relied upon (SC-003 precondition). - [ ] `hammerkit cache ls` lists each entry's task id, state key, size, and last-accessed time. - [ ] A backend that cannot supply size or last-used reports that policy as unavailable, not silently ignored. - [ ] Output routes through the `Environment`. ## Blocked by - None - can start immediately.

Comments