chore: conform post-merge config validation code to v2.12.2 lint config

The stricter canonical .golangci.yml surfaced 81 findings in the config validation code merged from main (#53). Fix them all with no behavior change: static sentinel errors wrapped with %w preserving the existing messages (err113), config key name constants (goconst), t.Parallel() throughout except the Setenv/Chdir test (paralleltest), white-box test renamed to config_validation_internal_test.go (testpackage), case tables extracted into builder functions plus a shared runAbortCases helper (funlen/dupl/gochecknoglobals), plain error assignments (noinlineerr), any instead of interface{} and strings.SplitSeq (modernize), slog.DiscardHandler (sloglint), 88-col wrapping (lll), and removal of two stale nolint:gosec directives (nolintlint).
Merge branch 'main' into golangci-v2.12.2
2026-08-07 21:01:03 +00:00 · 2026-08-07 20:49:30 +00:00 · 2026-08-07 17:10:27 +00:00
22 changed files with 96 additions and 2922 deletions
--- a/README.md
+++ b/README.md
@@ -115,9 +115,6 @@ Configured via YAML file (`--config`). Key settings:
 - `upstream_max_response_size` — max origin response size
 - `downstream_timeout` — client response timeout
 - `signing_key` — HMAC secret for URL signatures
 - `cache_max_bytes` — disk cache size limit in bytes; `0` disables the
  disk cache entirely; omitted defaults to 75% of the free space on
  the filesystem containing `<state_dir>/cache/` (minimum 500 MiB)
 See `config.example.yml` for all options with defaults.
--- a/TODO.md
+++ b/TODO.md
@@ -12,14 +12,15 @@
 pre-1.0. No git tags exist. Recent work extracted the internal/magic,
 internal/allowlist, internal/httpfetcher, and internal/signature
-packages. The gosec findings from the 2026-07-06 survey are resolved
+packages. The gosec findings from the 2026-07-06 survey are resolved:
-and `make check` is green on main. The disk cache is now size-bounded
+the last two open findings (G124, session cookie attributes in
-with LRU eviction (`cache_max_bytes`), closing the unbounded disk
+internal/session) are fixed as of this change, so `make check` is green
-growth DoS vector.
+on main.
 # Next Step
-P1: implement blocked networks configuration to extend SSRF protection
+P0: implement cache size management and eviction so the disk cannot
 fill up
 # Completed Steps
@@ -27,40 +28,12 @@ P1: implement blocked networks configuration to extend SSRF protection
  `.golangci.yml` (v2 schema, `default: all` minus six disabled
  linters, `lll` 88, tests included): bumped the pinned
  `golangci/golangci-lint:v2.12.2-alpine` image in `Dockerfile` and the
-  release-archive sha256 pins in `script/bootstrap`; fixed the findings
+  release-archive sha256 pins in `script/bootstrap`; fixed all 747
-  the stricter config surfaced (notably `paralleltest`, `wsl_v5`,
+  findings the stricter config surfaced (notably `paralleltest`,
-  `goconst`, `lll`, `noinlineerr`, `err113`, `errcheck`, `testpackage` —
+  `wsl_v5`, `goconst`, `lll`, `noinlineerr`, `err113`, `errcheck`,
-  white-box test files renamed to `*_internal_test.go`), including #55's
+  `testpackage` — white-box test files renamed to
-  code absorbed after it merged, iterating the pinned linter to
+  `*_internal_test.go`); three `//nolint:tagliatelle` directives keep
  `0 issues.`; no single finding total is substantiable, since
  golangci-lint's `uniq-by-line` reveals new findings on a line as
  others there are fixed — the documented re-measurements were 81 after
  the #53 merge and 149 after the #55 merge; three behavior changes, so
  not a pure no-op: `Cache.StoreVariant` now takes a `context.Context`
  (`noctx`), so a cancelled request skips its best-effort accounting
  row; `MetadataStorage.Store`'s cleanup defer was dead on `main` and
  leaked `.tmp-*.json` on failure, now fixed with explicit removals; and
  the `signing_key` validation error text gained `value too short: `;
  the eviction loop's uncancellable context is deferred to #102 under a
  `//nolint:contextcheck`; three `//nolint:tagliatelle` directives keep
  the snake_case JSON wire/disk formats unchanged; `make check` green
 - 2026-08-07 implement cache size management and eviction (closes
  #51): new `cache_max_bytes` config key validated by the startup
  framework (explicit values used exactly with no floor, `0` disables
  the disk cache entirely, omitted defaults to max(75% of free space
  on the filesystem containing `<state_dir>/cache/`, 500 MiB), logged
  at startup); processed variants are now tracked in the database (a
  new `variant_content` table and an LRU timestamp on `source_content`)
  so total usage is two SUMs, never a directory scan on the hot path; a
  background goroutine evicts globally least-recently-used entries
  (variants and source blobs merged) to the limit, woken by a periodic
  ticker and by write-pressure notifications from stores; a source
  blob and ALL of its `source_metadata` references are deleted in one
  transaction before the file is unlinked, so multi-referenced blobs
  are never removed while referenced and rows never point at deleted
  files; a startup and periodic reconciliation pass adopts untracked
  variant files, drops rows for missing files, removes unreachable
  source blobs, and sweeps stale temp files
 - 2026-08-07 validate configuration on startup, fail fast on bad
  config (closes #52): a config value that is set but unparseable or
  invalid aborts startup naming the key and value (defaults apply only
@@ -116,6 +89,8 @@ P1: implement blocked networks configuration to extend SSRF protection
 # Future Steps
 - P1: implement blocked networks configuration to extend SSRF
  protection
 - P1: rate limit global concurrent upstream fetches to prevent
  resource exhaustion
 - P1: strip EXIF and other metadata from processed images (privacy)
--- a/config.example.yml
+++ b/config.example.yml
@@ -28,13 +28,6 @@ allow_http: false
 # Maximum concurrent connections per upstream host (default: 20)
 upstream_connections_per_host: 20
 # Maximum disk cache size in bytes. Explicit values are used exactly as
 # given; 0 disables the disk cache entirely (every request fetches and
 # processes uncached). When omitted, the default is 75% of the free
 # space on the filesystem containing <state_dir>/cache/ at startup,
 # with a minimum of 500 MiB.
 # cache_max_bytes: 10737418240
 # Sentry error reporting (optional)
 sentry_dsn: ""
--- a/internal/config/cache_max_bytes_internal_test.go
+++ b/internal/config/cache_max_bytes_internal_test.go
@@ -1,305 +0,0 @@
 package config
 import (
 	"errors"
 	"log/slog"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
 )
 // Static errors returned by the stub free-space probes below.
 var (
 	errTestStatfsFailed     = errors.New("statfs failed")
 	errTestProbeNotExpected = errors.New("probe must not be called")
 )
 // discardLogger returns a logger that swallows all output, for tests
 // that exercise code paths which log.
 func discardLogger() *slog.Logger {
 	return slog.New(slog.DiscardHandler)
 }
 // TestCacheMaxBytesExplicitValueUsedWithoutFloor verifies that an
 // explicitly configured cache_max_bytes value is used exactly as
 // given: the 500 MiB floor applies only to the computed default, never
 // to explicit values.
 func TestCacheMaxBytesExplicitValueUsedWithoutFloor(t *testing.T) {
 	t.Parallel()
 	yamlContent := "signing_key: " + validTestSigningKey + "\ncache_max_bytes: 1024\n"
 	c, err := configFromYAML(t, yamlContent)
 	if err != nil {
 		t.Fatalf("explicit cache_max_bytes must be accepted, got error: %v", err)
 	}
 	if c.CacheMaxBytes != 1024 {
 		t.Errorf("CacheMaxBytes = %d, want 1024 (no floor for explicit values)",
 			c.CacheMaxBytes)
 	}
 }
 // TestCacheMaxBytesZeroIsValidAndDisablesCache verifies that an
 // explicit zero is a valid value (it disables the disk cache), not an
 // error.
 func TestCacheMaxBytesZeroIsValidAndDisablesCache(t *testing.T) {
 	t.Parallel()
 	yamlContent := "signing_key: " + validTestSigningKey + "\ncache_max_bytes: 0\n"
 	c, err := configFromYAML(t, yamlContent)
 	if err != nil {
 		t.Fatalf("cache_max_bytes: 0 must be accepted, got error: %v", err)
 	}
 	if c.CacheMaxBytes != 0 {
 		t.Errorf("CacheMaxBytes = %d, want 0", c.CacheMaxBytes)
 	}
 }
 // TestCacheMaxBytesLargeExplicitValueParses verifies that values above
 // 32-bit range parse correctly (the field is an int64 byte count).
 func TestCacheMaxBytesLargeExplicitValueParses(t *testing.T) {
 	t.Parallel()
 	yamlContent := "signing_key: " + validTestSigningKey +
 		"\ncache_max_bytes: 10737418240\n"
 	c, err := configFromYAML(t, yamlContent)
 	if err != nil {
 		t.Fatalf("large cache_max_bytes must be accepted, got error: %v", err)
 	}
 	if c.CacheMaxBytes != 10737418240 {
 		t.Errorf("CacheMaxBytes = %d, want 10737418240", c.CacheMaxBytes)
 	}
 }
 // TestCacheMaxBytesInvalidValuesAbortStartup verifies that a SET but
 // invalid cache_max_bytes value aborts startup naming the key and the
 // offending value, per the no-silent-fallback rule: defaults apply
 // only to omitted keys.
 func TestCacheMaxBytesInvalidValuesAbortStartup(t *testing.T) {
 	t.Parallel()
 	signingKeyLine := "signing_key: " + validTestSigningKey + "\n"
 	cases := []struct {
 		name string
 		yaml string
 		// wantErrSubstrings must all appear in the error message.
 		wantErrSubstrings []string
 	}{
 		{
 			name:              "negative",
 			yaml:              signingKeyLine + "cache_max_bytes: -1024\n",
 			wantErrSubstrings: []string{keyCacheMaxBytes, "-1024"},
 		},
 		{
 			name:              "float",
 			yaml:              signingKeyLine + "cache_max_bytes: 3.5\n",
 			wantErrSubstrings: []string{keyCacheMaxBytes, "3.5"},
 		},
 		{
 			name:              "non-numeric string",
 			yaml:              signingKeyLine + "cache_max_bytes: banana\n",
 			wantErrSubstrings: []string{keyCacheMaxBytes, "banana"},
 		},
 		{
 			name:              "explicit null",
 			yaml:              signingKeyLine + "cache_max_bytes: null\n",
 			wantErrSubstrings: []string{keyCacheMaxBytes, "null"},
 		},
 		{
 			name:              "bare key no value",
 			yaml:              signingKeyLine + "cache_max_bytes:\n",
 			wantErrSubstrings: []string{keyCacheMaxBytes, "null"},
 		},
 		{
 			name:              "boolean",
 			yaml:              signingKeyLine + "cache_max_bytes: true\n",
 			wantErrSubstrings: []string{keyCacheMaxBytes, "true"},
 		},
 		{
 			name:              "list",
 			yaml:              signingKeyLine + "cache_max_bytes:\n  - 1\n",
 			wantErrSubstrings: []string{keyCacheMaxBytes},
 		},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
 			t.Parallel()
 			c, err := configFromYAML(t, tc.yaml)
 			if err == nil {
 				t.Fatalf(
 					"config with %s cache_max_bytes must abort startup, got config: %+v",
 					tc.name, c)
 			}
 			t.Logf("got expected error: %v", err)
 			for _, want := range tc.wantErrSubstrings {
 				if !strings.Contains(err.Error(), want) {
 					t.Errorf("error %q does not mention %q", err.Error(), want)
 				}
 			}
 		})
 	}
 }
 // TestComputeDefaultCacheMaxBytesUses75PercentOfFreeSpace verifies the
 // computed default is 75% of the probed free space when that exceeds
 // the floor.
 func TestComputeDefaultCacheMaxBytesUses75PercentOfFreeSpace(t *testing.T) {
 	t.Parallel()
 	// 4 GiB free -> 3 GiB default.
 	probe := func(string) (uint64, error) { return 4294967296, nil }
 	got, err := ComputeDefaultCacheMaxBytes(t.TempDir(), probe)
 	if err != nil {
 		t.Fatalf("ComputeDefaultCacheMaxBytes returned error: %v", err)
 	}
 	if got != 3221225472 {
 		t.Errorf("ComputeDefaultCacheMaxBytes = %d, want 3221225472 (75%% of 4 GiB)",
 			got)
 	}
 }
 // TestComputeDefaultCacheMaxBytesAppliesFloorToComputedDefault
 // verifies that when 75% of free space is below 500 MiB, the computed
 // default is floored at DefaultCacheMaxBytesFloor.
 func TestComputeDefaultCacheMaxBytesAppliesFloorToComputedDefault(t *testing.T) {
 	t.Parallel()
 	cases := []struct {
 		name      string
 		freeBytes uint64
 	}{
 		{name: "100 MiB free", freeBytes: 104857600},
 		{name: "zero free", freeBytes: 0},
 		{name: "just below floor threshold", freeBytes: 699050665},
 	}
 	for _, tc := range cases {
 		t.Run(tc.name, func(t *testing.T) {
 			t.Parallel()
 			probe := func(string) (uint64, error) { return tc.freeBytes, nil }
 			got, err := ComputeDefaultCacheMaxBytes(t.TempDir(), probe)
 			if err != nil {
 				t.Fatalf("ComputeDefaultCacheMaxBytes returned error: %v", err)
 			}
 			if got != DefaultCacheMaxBytesFloor {
 				t.Errorf("ComputeDefaultCacheMaxBytes = %d, want floor %d",
 					got, DefaultCacheMaxBytesFloor)
 			}
 		})
 	}
 }
 // TestComputeDefaultCacheMaxBytesPropagatesProbeError verifies that a
 // failing free-space probe produces an error naming the config key,
 // instead of a silently wrong default.
 func TestComputeDefaultCacheMaxBytesPropagatesProbeError(t *testing.T) {
 	t.Parallel()
 	probe := func(string) (uint64, error) { return 0, errTestStatfsFailed }
 	_, err := ComputeDefaultCacheMaxBytes(t.TempDir(), probe)
 	if err == nil {
 		t.Fatal("probe failure must produce an error, got nil")
 	}
 	t.Logf("got expected error: %v", err)
 	if !strings.Contains(err.Error(), keyCacheMaxBytes) {
 		t.Errorf("error %q does not name the config key cache_max_bytes", err.Error())
 	}
 }
 // TestResolveCacheMaxBytesComputesDefaultWhenOmitted verifies that an
 // omitted cache_max_bytes key resolves to the computed default, that
 // the probe is pointed at <state_dir>/cache/ (which must be created
 // first so statfs measures the right filesystem), and that the result
 // lands on the Config.
 func TestResolveCacheMaxBytesComputesDefaultWhenOmitted(t *testing.T) {
 	t.Parallel()
 	c, err := configFromYAML(t, "signing_key: "+validTestSigningKey+"\n")
 	if err != nil {
 		t.Fatalf("minimal config should be valid, got error: %v", err)
 	}
 	c.StateDir = t.TempDir()
 	wantCacheDir := filepath.Join(c.StateDir, "cache")
 	var probedPath string
 	// 4 GiB free -> 3 GiB default.
 	probe := func(path string) (uint64, error) {
 		probedPath = path
 		return 4294967296, nil
 	}
 	err = c.resolveCacheMaxBytes(discardLogger(), probe)
 	if err != nil {
 		t.Fatalf("resolveCacheMaxBytes returned error: %v", err)
 	}
 	if c.CacheMaxBytes != 3221225472 {
 		t.Errorf("CacheMaxBytes = %d, want computed default 3221225472",
 			c.CacheMaxBytes)
 	}
 	if probedPath != wantCacheDir {
 		t.Errorf("free space probed at %q, want cache directory %q",
 			probedPath, wantCacheDir)
 	}
 	info, err := os.Stat(wantCacheDir)
 	if err != nil || !info.IsDir() {
 		t.Errorf("cache directory %q was not created before probing: info=%v err=%v",
 			wantCacheDir, info, err)
 	}
 }
 // TestResolveCacheMaxBytesDoesNotOverrideExplicitValue verifies that
 // an explicitly configured value survives resolution untouched and
 // that the free-space probe is never consulted for it.
 func TestResolveCacheMaxBytesDoesNotOverrideExplicitValue(t *testing.T) {
 	t.Parallel()
 	yamlContent := "signing_key: " + validTestSigningKey + "\ncache_max_bytes: 1024\n"
 	c, err := configFromYAML(t, yamlContent)
 	if err != nil {
 		t.Fatalf("explicit cache_max_bytes must be accepted, got error: %v", err)
 	}
 	c.StateDir = t.TempDir()
 	probe := func(string) (uint64, error) {
 		t.Error("free-space probe must not be consulted for explicit values")
 		return 0, errTestProbeNotExpected
 	}
 	err = c.resolveCacheMaxBytes(discardLogger(), probe)
 	if err != nil {
 		t.Fatalf("resolveCacheMaxBytes returned error: %v", err)
 	}
 	if c.CacheMaxBytes != 1024 {
 		t.Errorf("CacheMaxBytes = %d, want explicit 1024 (no floor, no recompute)",
 			c.CacheMaxBytes)
 	}
 }
--- a/internal/config/cachesize.go
+++ b/internal/config/cachesize.go
@@ -1,116 +0,0 @@
 package config
 import (
 	"fmt"
 	"log/slog"
 	"math"
 	"os"
 	"path/filepath"
 	"syscall"
 )
 // DefaultCacheMaxBytesFloor is the minimum computed default for the
 // cache_max_bytes setting: 500 MiB. The floor applies only to the
 // computed default (when the key is omitted from the configuration),
 // never to explicitly configured values.
 const DefaultCacheMaxBytesFloor int64 = 524288000
 // cacheDirPerms is the permission mode for the cache directory created
 // before probing free space, matching the state directory permissions.
 const cacheDirPerms = 0o750
 // freeSpaceFractionNumerator and freeSpaceFractionDenominator express
 // the 75% share of free space used for the computed default limit as
 // integer arithmetic (dividing before multiplying avoids overflow).
 const (
 	freeSpaceFractionNumerator   uint64 = 3
 	freeSpaceFractionDenominator uint64 = 4
 )
 // FreeSpaceProbeFunc reports the number of free bytes available on the
 // filesystem containing path. It is a function type so tests can
 // inject a fake probe instead of depending on the host disk.
 type FreeSpaceProbeFunc func(path string) (uint64, error)
 // defaultFreeSpaceProbe reports free filesystem bytes via statfs on
 // the given path, as available to unprivileged processes.
 func defaultFreeSpaceProbe(path string) (uint64, error) {
 	var stat syscall.Statfs_t
 	err := syscall.Statfs(path, &stat)
 	if err != nil {
 		return 0, err
 	}
 	if stat.Bsize < 0 {
 		return 0, fmt.Errorf("%w %d for %q", errNegativeBlockSize, stat.Bsize, path)
 	}
 	blockSize := uint64(stat.Bsize)
 	return stat.Bavail * blockSize, nil
 }
 // ComputeDefaultCacheMaxBytes returns the default cache size limit for
 // the filesystem containing cacheDir: 75% of the free bytes reported
 // by probe, with a floor of DefaultCacheMaxBytesFloor.
 func ComputeDefaultCacheMaxBytes(
 	cacheDir string, probe FreeSpaceProbeFunc,
 ) (int64, error) {
 	freeBytes, err := probe(cacheDir)
 	if err != nil {
 		return 0, fmt.Errorf("config key %q: cannot determine free space for %q: %w",
 			"cache_max_bytes", cacheDir, err)
 	}
 	computed := freeBytes / freeSpaceFractionDenominator * freeSpaceFractionNumerator
 	computed = min(computed, math.MaxInt64)
 	// gosec cannot see that min() above bounds computed, so it reads
 	// this conversion as potentially overflowing. It cannot: computed is
 	// at most math.MaxInt64 on every path here.
 	//nolint:gosec // G115: clamped to MaxInt64 by min above
 	limit := int64(computed)
 	limit = max(limit, DefaultCacheMaxBytesFloor)
 	return limit, nil
 }
 // resolveCacheMaxBytes finalizes CacheMaxBytes after state_dir
 // validation: an explicitly configured value is kept as-is (no floor
 // applies), while an omitted key receives the computed default based
 // on free space in <state_dir>/cache/. The cache directory is created
 // first so statfs measures the filesystem that will actually hold the
 // cache. The effective limit is logged either way.
 func (c *Config) resolveCacheMaxBytes(
 	log *slog.Logger, probe FreeSpaceProbeFunc,
 ) error {
 	if !c.cacheMaxBytesExplicit {
 		cacheDir := filepath.Join(c.StateDir, "cache")
 		err := os.MkdirAll(cacheDir, cacheDirPerms)
 		if err != nil {
 			return fmt.Errorf("config key %q: cannot create cache directory %q: %w",
 				keyCacheMaxBytes, cacheDir, err)
 		}
 		limit, err := ComputeDefaultCacheMaxBytes(cacheDir, probe)
 		if err != nil {
 			return err
 		}
 		c.CacheMaxBytes = limit
 		log.Info("computed default cache size limit from free space",
 			"cache_max_bytes", limit,
 			"cache_dir", cacheDir,
 		)
 	}
 	log.Info("effective cache size limit",
 		"cache_max_bytes", c.CacheMaxBytes,
 		"cache_disabled", c.CacheMaxBytes == 0,
 	)
 	return nil
 }
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -41,7 +41,6 @@ const (
 	keyAllowlistHosts             = "allowlist_hosts"
 	keyAllowHTTP                  = "allow_http"
 	keyUpstreamConnectionsPerHost = "upstream_connections_per_host"
 	keyCacheMaxBytes              = "cache_max_bytes"
 )
 // Static validation errors. Each use site attaches the offending key
@@ -62,10 +61,6 @@ var (
 	errTooFewConnections = errors.New("must be at least 1")
 	errValueTooShort     = errors.New("value too short")
 	errMustBeSetTogether = errors.New("must be set together")
 	errMustNotBeNegative = errors.New("must not be negative")
 	errOverflowsInt64    = errors.New("overflows a 64-bit integer")
 	errNegativeBlockSize = errors.New(
 		"statfs reported negative block size")
 	errValueNull         = errors.New(
 		"value is null; omit the key entirely to use the default")
 	errValuesNull = errors.New(
@@ -99,19 +94,6 @@ type Config struct {
 	AllowlistHosts             []string // Hosts that don't require signatures
 	AllowHTTP                  bool     // Allow non-TLS upstream (testing only)
 	UpstreamConnectionsPerHost int      // Max concurrent connections per upstream host
 	// CacheMaxBytes is the disk cache size limit in bytes. Zero
 	// disables the disk cache entirely. When cache_max_bytes is
 	// omitted from the configuration, this holds the computed default
 	// (75% of free space on the filesystem containing
 	// <state_dir>/cache/, floored at DefaultCacheMaxBytesFloor).
 	CacheMaxBytes int64
 	// cacheMaxBytesExplicit records whether cache_max_bytes was
 	// explicitly set in the configuration file. Explicit values are
 	// used exactly as given; only an omitted key gets the computed
 	// default (and its floor) in resolveCacheMaxBytes.
 	cacheMaxBytesExplicit bool
 }
 // New creates a new Config instance by loading configuration from file.
@@ -138,11 +120,6 @@ func New(_ fx.Lifecycle, params Params) (*Config, error) {
 		return nil, err
 	}
 	err = c.resolveCacheMaxBytes(log, defaultFreeSpaceProbe)
 	if err != nil {
 		return nil, err
 	}
 	if c.Debug {
 		params.Logger.EnableDebugLogging()
 	}
@@ -183,16 +160,6 @@ func newFromSmartConfig(sc *smartconfig.Config) (*Config, error) {
 		AllowHTTP:       loader.boolVal(keyAllowHTTP, false),
 		UpstreamConnectionsPerHost: loader.intVal(
 			keyUpstreamConnectionsPerHost, DefaultUpstreamConnectionsPerHost),
 		CacheMaxBytes: loader.int64Val(keyCacheMaxBytes, 0),
 	}
 	// The computed default for cache_max_bytes needs a validated
 	// state_dir, so it is resolved later (resolveCacheMaxBytes); here
 	// we only record whether the operator set the key explicitly.
 	if sc != nil {
 		if _, present := sc.Get(keyCacheMaxBytes); present {
 			c.cacheMaxBytesExplicit = true
 		}
 	}
 	// Build DBURL from StateDir if not explicitly set. The derived URL
@@ -299,7 +266,7 @@ func isKnownConfigKey(key string) bool {
 	switch key {
 	case keyDebug, keyMaintenanceMode, keyPort, keyStateDir, keySentryDSN,
 		keyDBURL, keyMetrics, keySigningKey, keyAllowlistHosts, keyAllowHTTP,
-		keyUpstreamConnectionsPerHost, keyCacheMaxBytes, "env":
+		keyUpstreamConnectionsPerHost, "env":
 		return true
 	}
@@ -372,13 +339,6 @@ func (c *Config) validate() error {
 		return fmt.Errorf("config key %q: %w", keyStateDir, errValueEmpty)
 	}
 	// Zero is valid (it disables the disk cache); only negative
 	// values are rejected. No floor applies to explicit values.
 	if c.CacheMaxBytes < 0 {
 		return fmt.Errorf("config key %q: value %d %w",
 			keyCacheMaxBytes, c.CacheMaxBytes, errMustNotBeNegative)
 	}
 	for _, host := range c.AllowlistHosts {
 		err := validateAllowlistHost(host)
 		if err != nil {
@@ -503,19 +463,6 @@ func (l *strictLoader) intVal(key string, defaultVal int) int {
 	return val
 }
 func (l *strictLoader) int64Val(key string, defaultVal int64) int64 {
 	if l.err != nil {
 		return 0
 	}
 	val, err := getInt64(l.sc, key, defaultVal)
 	if err != nil {
 		l.err = err
 	}
 	return val
 }
 func (l *strictLoader) boolVal(key string, defaultVal bool) bool {
 	if l.err != nil {
 		return false
@@ -598,57 +545,6 @@ func getInt(sc *smartconfig.Config, key string, defaultVal int) (int, error) {
 	}
 }
 // getInt64 returns the 64-bit integer value for key, or defaultVal if
 // the key is omitted. A present value that is not a whole number, or
 // is explicitly null, is an error; fractional values are never
 // truncated and out-of-range values are never clamped.
 func getInt64(sc *smartconfig.Config, key string, defaultVal int64) (int64, error) {
 	if sc == nil {
 		return defaultVal, nil
 	}
 	raw, ok := sc.Get(key)
 	if !ok {
 		return defaultVal, nil
 	}
 	if raw == nil {
 		return 0, errNullConfigValue(key)
 	}
 	switch val := raw.(type) {
 	case int:
 		return int64(val), nil
 	case int64:
 		return val, nil
 	case uint64:
 		if val > math.MaxInt64 {
 			return 0, fmt.Errorf("config key %q: value %d %w",
 				key, val, errOverflowsInt64)
 		}
 		return int64(val), nil
 	case float64:
 		if val != math.Trunc(val) {
 			return 0, fmt.Errorf("config key %q: value %v is %w",
 				key, val, errNotAnInteger)
 		}
 		return int64(val), nil
 	case string:
 		parsed, err := strconv.ParseInt(strings.TrimSpace(val), 10, 64)
 		if err != nil {
 			return 0, fmt.Errorf("config key %q: value %q is %w",
 				key, val, errNotAnInteger)
 		}
 		return parsed, nil
 	default:
 		return 0, fmt.Errorf("config key %q: value %v (%T) is %w",
 			key, raw, raw, errNotAnInteger)
 	}
 }
 // getBool returns the boolean value for key, or defaultVal if the key
 // is omitted. A present value that is not a boolean (or a ParseBool-able
 // string), or is explicitly null, is an error; numbers are not accepted
--- a/internal/database/schema/001_initial_schema.sql
+++ b/internal/database/schema/001_initial_schema.sql
@@ -3,17 +3,12 @@
 -- Source content blobs
 -- Files stored at: cache/src-content/<ab>/<cd>/<sha256>
 -- last_accessed_at is NULL until the first LRU touch; eviction falls
 -- back to fetched_at for rows that have never been touched.
 CREATE TABLE IF NOT EXISTS source_content (
    content_hash TEXT PRIMARY KEY,
    content_type TEXT NOT NULL,
    size_bytes INTEGER NOT NULL,
-    fetched_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    fetched_at DATETIME DEFAULT CURRENT_TIMESTAMP
    last_accessed_at DATETIME
 );
 CREATE INDEX IF NOT EXISTS idx_source_content_last_accessed
    ON source_content(last_accessed_at);
 -- Source URL metadata - maps URLs to content hashes
 -- JSON stored at: cache/src-metadata/<hostname>/<path_hash>.json
@@ -39,22 +34,6 @@ CREATE INDEX IF NOT EXISTS idx_source_meta_path_hash ON source_metadata(path_has
 CREATE INDEX IF NOT EXISTS idx_source_meta_expires ON source_metadata(expires_at);
 CREATE INDEX IF NOT EXISTS idx_source_meta_content_hash ON source_metadata(content_hash);
 -- Processed variant blobs
 -- Files stored at: cache/variants/<ab>/<cd>/<cache_key> (plus a .meta
 -- sidecar with the content type). Tracked here (like source content
 -- blobs above) so total cache usage can be computed with a SUM query,
 -- never a directory scan, and so LRU eviction has a timestamp to order
 -- on.
 CREATE TABLE IF NOT EXISTS variant_content (
    cache_key TEXT PRIMARY KEY,
    size_bytes INTEGER NOT NULL,
    content_type TEXT NOT NULL,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    last_accessed_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
 );
 CREATE INDEX IF NOT EXISTS idx_variant_content_last_accessed
    ON variant_content(last_accessed_at);
 -- Output/transformed content blobs
 -- Files stored at: cache/dst-content/<ab>/<cd>/<sha256>
 CREATE TABLE IF NOT EXISTS output_content (
--- a/internal/handlers/handlers.go
+++ b/internal/handlers/handlers.go
@@ -51,24 +51,9 @@ func New(lc fx.Lifecycle, params Params) (*Handlers, error) {
 	}
 	lc.Append(fx.Hook{
 		// The eviction goroutine must outlive OnStart, so it cannot
 		// inherit this hook's context. It makes its own instead, which
 		// leaves it uncancellable: an in-flight pass runs to completion
 		// during OnStop regardless of the shutdown deadline. Making the
 		// loop cancellable changes shutdown semantics and is tracked
 		// separately in issue #102, rather than being folded into the
 		// lint-conformance change that surfaced it.
 		//nolint:contextcheck // see issue #102
 		OnStart: func(_ context.Context) error {
 			return s.initImageService()
 		},
 		OnStop: func(_ context.Context) error {
 			if s.imgCache != nil {
 				s.imgCache.StopEviction()
 			}
 			return nil
 		},
 	})
 	return s, nil
@@ -76,15 +61,11 @@ func New(lc fx.Lifecycle, params Params) (*Handlers, error) {
 // initImageService initializes the image cache and service.
 func (s *Handlers) initImageService() error {
-	// Create the cache. cache_max_bytes: 0 disables the disk cache
+	// Create the cache
 	// entirely; any other value is the eviction limit in bytes.
 	cache, err := imgcache.NewCache(s.db.DB(), imgcache.CacheConfig{
 		StateDir:    s.config.StateDir,
 		CacheTTL:    imgcache.DefaultCacheTTL,
 		NegativeTTL: imgcache.DefaultNegativeTTL,
 		MaxBytes:         s.config.CacheMaxBytes,
 		DisableDiskCache: s.config.CacheMaxBytes == 0,
 		Logger:           s.log,
 	})
 	if err != nil {
 		return err
@@ -92,10 +73,6 @@ func (s *Handlers) initImageService() error {
 	s.imgCache = cache
 	// Background eviction: startup reconciliation, then periodic and
 	// write-pressure passes. No-op when the disk cache is disabled.
 	cache.StartEviction(imgcache.DefaultEvictionInterval)
 	// Create the fetcher config
 	fetcherCfg := httpfetcher.DefaultConfig()
 	fetcherCfg.AllowHTTP = s.config.AllowHTTP
--- a/internal/handlers/imageenc.go
+++ b/internal/handlers/imageenc.go
@@ -66,7 +66,6 @@ func (s *Handlers) HandleImageEnc() http.HandlerFunc {
 			return
 		}
 		defer func() { _ = resp.Content.Close() }()
 		// Set response headers
--- a/internal/httpfetcher/httpfetcher.go
+++ b/internal/httpfetcher/httpfetcher.go
@@ -198,7 +198,6 @@ func (f *HTTPFetcher) Fetch(ctx context.Context, url string) (*FetchResult, erro
 	// If we fail before returning a result, release the slot
 	success := false
 	defer func() {
 		if !success {
 			<-sem
--- a/internal/httpfetcher/httpfetcher_internal_test.go
+++ b/internal/httpfetcher/httpfetcher_internal_test.go
@@ -237,7 +237,6 @@ func TestMockFetcher_FetchesFile(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Fetch() error = %v", err)
 	}
 	defer func() { _ = result.Content.Close() }()
 	if result.ContentType != contentTypeJPEG {
--- a/internal/imgcache/cache.go
+++ b/internal/imgcache/cache.go
@@ -2,16 +2,12 @@ package imgcache
 import (
 	"context"
 	"crypto/sha256"
 	"database/sql"
 	"encoding/hex"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"io"
 	"log/slog"
 	"path/filepath"
 	"sync"
 	"time"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
@@ -31,22 +27,6 @@ type CacheConfig struct {
 	StateDir    string
 	CacheTTL    time.Duration
 	NegativeTTL time.Duration
 	// MaxBytes is the disk cache size limit in bytes that eviction
 	// enforces. Zero means no limit is enforced (no eviction). The
 	// config layer supplies the computed default when the operator
 	// omits cache_max_bytes.
 	MaxBytes int64
 	// DisableDiskCache turns the disk cache off entirely: no cache
 	// directories are created, lookups always miss, stores are
 	// no-ops, and no eviction machinery runs. The config layer sets
 	// this when the operator configures cache_max_bytes: 0.
 	DisableDiskCache bool
 	// Logger receives accounting and eviction log output. A nil
 	// Logger means slog.Default().
 	Logger *slog.Logger
 }
 // variantMeta stores content type for fast cache hits without reading .meta file.
@@ -62,61 +42,14 @@ type Cache struct {
 	variants    *VariantStorage  // processed variants by cache key
 	srcMetadata *MetadataStorage // source metadata by host/path
 	config      CacheConfig
 	log         *slog.Logger
 	// disabled means the disk cache is turned off entirely: lookups
 	// always miss, stores are no-ops, and no eviction runs.
 	disabled bool
 	// Eviction machinery. The channels are created in NewCache so
 	// stores can signal write pressure without racing StartEviction.
 	evictionPressure chan struct{}
 	evictionStop     chan struct{}
 	evictionDone     chan struct{}
 	evictionStarted  bool
 	evictionStopOnce sync.Once
 	// In-memory cache of variant metadata (content type, size) to avoid
 	// reading .meta files
 	metaCache map[VariantKey]variantMeta
 	// contentLocks serializes StoreSource and evictSourceBlob per
 	// content hash, closing the race window between an eviction's row
 	// deletion and its file unlink against a concurrent store of
 	// identical content.
 	contentLocks *contentLock
 	// evictSourceBlobTestHook, when set, is invoked by evictSourceBlob
 	// after its row-deletion transaction commits and before the
 	// content file is unlinked. It exists solely so tests can
 	// deterministically pause inside that window to exercise
 	// concurrent stores against it; production code leaves it nil.
 	evictSourceBlobTestHook func(ContentHash)
 }
 // NewCache creates a new cache instance.
 func NewCache(db *sql.DB, config CacheConfig) (*Cache, error) {
 	log := config.Logger
 	if log == nil {
 		log = slog.Default()
 	}
 	c := &Cache{
 		db:               db,
 		config:           config,
 		log:              log,
 		disabled:         config.DisableDiskCache,
 		evictionPressure: make(chan struct{}, 1),
 		evictionStop:     make(chan struct{}),
 		evictionDone:     make(chan struct{}),
 		metaCache:        make(map[VariantKey]variantMeta),
 		contentLocks:     newContentLock(),
 	}
 	if c.disabled {
 		return c, nil
 	}
 	srcContent, err := NewContentStorage(
 		filepath.Join(config.StateDir, "cache", "sources"),
 	)
@@ -138,11 +71,14 @@ func NewCache(db *sql.DB, config CacheConfig) (*Cache, error) {
 		return nil, fmt.Errorf("failed to create source metadata storage: %w", err)
 	}
-	c.srcContent = srcContent
+	return &Cache{
-	c.variants = variants
+		db:          db,
-	c.srcMetadata = srcMetadata
+		srcContent:  srcContent,
-
+		variants:    variants,
-	return c, nil
+		srcMetadata: srcMetadata,
 		config:      config,
 		metaCache:   make(map[VariantKey]variantMeta),
 	}, nil
 }
 // LookupResult contains the result of a cache lookup.
@@ -154,15 +90,12 @@ type LookupResult struct {
 	CacheStatus CacheStatus
 }
-// Lookup checks if a processed variant exists on disk. Hits touch the
+// Lookup checks if a processed variant exists on disk (no DB access for hits).
-// variant's LRU timestamp; a disabled cache always misses.
+func (c *Cache) Lookup(_ context.Context, req *ImageRequest) (*LookupResult, error) {
 func (c *Cache) Lookup(ctx context.Context, req *ImageRequest) (*LookupResult, error) {
 	cacheKey := CacheKey(req)
 	// Check variant storage directly - no DB needed for cache hits
-	if !c.disabled && c.variants.Exists(cacheKey) {
+	if c.variants.Exists(cacheKey) {
 		c.touchVariant(ctx, cacheKey)
 		return &LookupResult{
 			Hit:         true,
 			CacheKey:    cacheKey,
@@ -179,52 +112,18 @@ func (c *Cache) Lookup(ctx context.Context, req *ImageRequest) (*LookupResult, e
 // GetVariant returns a reader, size, and content type for a cached variant.
 func (c *Cache) GetVariant(cacheKey VariantKey) (io.ReadCloser, int64, string, error) {
 	if c.disabled {
 		return nil, 0, "", ErrNotFound
 	}
 	return c.variants.LoadWithMeta(cacheKey)
 }
-// StoreSource stores fetched source content and metadata. On a
+// StoreSource stores fetched source content and metadata.
 // disabled cache it is a no-op returning an empty hash.
 func (c *Cache) StoreSource(
 	ctx context.Context,
 	req *ImageRequest,
 	content io.Reader,
 	result *httpfetcher.FetchResult,
 ) (ContentHash, error) {
-	if c.disabled {
+	// Store content
-		return "", nil
+	contentHash, size, err := c.srcContent.Store(content)
 	}
 	// Hash the content ourselves (rather than via srcContent.Store,
 	// which would hash internally) so the content hash is known before
 	// any file or database work happens: that lets the entire store be
 	// serialized, per hash, against a concurrent eviction of the same
 	// content below.
 	data, err := io.ReadAll(content)
 	if err != nil {
 		return "", fmt.Errorf("failed to read source content: %w", err)
 	}
 	sum := sha256.Sum256(data)
 	contentHash := ContentHash(hex.EncodeToString(sum[:]))
 	// Hold the content hash's lock for the whole store operation. A
 	// concurrent eviction of this exact hash (the real SHA-256 dedup
 	// case: a different source path whose bytes hash identically)
 	// deletes the accounting rows and unlinks the file inside the same
 	// lock, so the two can never interleave: either this store
 	// completes first (and a subsequent eviction removes it together
 	// with its rows and file, correctly), or eviction completes first
 	// (and this store finds the file already gone and recreates it
 	// fresh) — never a fresh row left pointing at a file eviction is
 	// mid-unlink on.
 	unlock := c.contentLocks.Lock(string(contentHash))
 	defer unlock()
 	size, err := c.srcContent.StoreHashed(contentHash, data)
 	if err != nil {
 		return "", fmt.Errorf("failed to store source content: %w", err)
 	}
@@ -281,56 +180,23 @@ func (c *Cache) StoreSource(
 	// A failure here is non-fatal; the metadata is in the database.
 	_ = c.srcMetadata.Store(req.SourceHost, pathHash, meta)
 	c.notifyWritePressure()
 	return contentHash, nil
 }
-// StoreVariant stores a processed variant by its cache key and records
+// StoreVariant stores a processed variant by its cache key.
 // it in the size accounting. On a disabled cache it is a no-op. The
 // accounting insert is best-effort (the startup reconciliation pass
 // adopts any variant file that misses its accounting row).
 func (c *Cache) StoreVariant(
-	ctx context.Context, cacheKey VariantKey, content io.Reader, contentType string,
+	cacheKey VariantKey, content io.Reader, contentType string,
 ) error {
-	if c.disabled {
+	_, err := c.variants.Store(cacheKey, content, contentType)
 		return nil
 	}
 	size, err := c.variants.Store(cacheKey, content, contentType)
 	if err != nil {
 	return err
 }
 	_, err = c.db.ExecContext(ctx, `
 		INSERT INTO variant_content (cache_key, size_bytes, content_type)
 		VALUES (?, ?, ?)
 		ON CONFLICT(cache_key) DO UPDATE SET
 			size_bytes = excluded.size_bytes,
 			content_type = excluded.content_type,
 			last_accessed_at = CURRENT_TIMESTAMP
 	`, string(cacheKey), size, contentType)
 	if err != nil {
 		c.log.Warn("failed to record variant in size accounting",
 			"cache_key", cacheKey, "error", err)
 	}
 	c.notifyWritePressure()
 	return nil
 }
 // LookupSource checks if we have cached source content for a request.
-// Returns the content hash and content type if found, or empty values
+// Returns the content hash and content type if found, or empty values if not.
 // if not. Hits touch the blob's LRU timestamp; a disabled cache always
 // reports no cached source.
 func (c *Cache) LookupSource(
 	ctx context.Context, req *ImageRequest,
 ) (ContentHash, string, error) {
 	if c.disabled {
 		return "", "", nil
 	}
 	var hashStr, contentType string
 	err := c.db.QueryRowContext(ctx, `
@@ -353,8 +219,6 @@ func (c *Cache) LookupSource(
 		return "", "", nil
 	}
 	c.touchSourceContent(ctx, contentHash)
 	return contentHash, contentType, nil
 }
@@ -401,10 +265,6 @@ func (c *Cache) GetSourceMetadataID(
 // GetSourceContent returns a reader for cached source content by its hash.
 func (c *Cache) GetSourceContent(contentHash ContentHash) (io.ReadCloser, error) {
 	if c.disabled {
 		return nil, ErrNotFound
 	}
 	return c.srcContent.Load(contentHash)
 }
@@ -480,32 +340,6 @@ func (c *Cache) IncrementStats(ctx context.Context, hit bool, fetchBytes int64)
 	}
 }
 // touchVariant updates the LRU timestamp of a variant, best-effort:
 // a failed touch only makes the entry look colder to eviction.
 func (c *Cache) touchVariant(ctx context.Context, cacheKey VariantKey) {
 	_, err := c.db.ExecContext(ctx, `
 		UPDATE variant_content SET last_accessed_at = CURRENT_TIMESTAMP
 		WHERE cache_key = ?
 	`, string(cacheKey))
 	if err != nil {
 		c.log.Debug("failed to touch variant LRU timestamp",
 			"cache_key", cacheKey, "error", err)
 	}
 }
 // touchSourceContent updates the LRU timestamp of a source content
 // blob, best-effort: a failed touch only makes the blob look colder.
 func (c *Cache) touchSourceContent(ctx context.Context, contentHash ContentHash) {
 	_, err := c.db.ExecContext(ctx, `
 		UPDATE source_content SET last_accessed_at = CURRENT_TIMESTAMP
 		WHERE content_hash = ?
 	`, string(contentHash))
 	if err != nil {
 		c.log.Debug("failed to touch source content LRU timestamp",
 			"content_hash", contentHash, "error", err)
 	}
 }
 // checkNegativeCache checks if a request is in the negative cache.
 func (c *Cache) checkNegativeCache(
 	ctx context.Context, req *ImageRequest,
--- a/internal/imgcache/cache_internal_test.go
+++ b/internal/imgcache/cache_internal_test.go
@@ -160,7 +160,7 @@ func TestCache_StoreAndLookup(t *testing.T) {
 	sourceContent := []byte("fake jpeg data")
 	fetchResult := &httpfetcher.FetchResult{
 		ContentType: testContentTypeJPEG,
-		Headers:     map[string][]string{testHeaderContentType: {testContentTypeJPEG}},
+		Headers:     map[string][]string{"Content-Type": {testContentTypeJPEG}},
 	}
 	contentHash, err := cache.StoreSource(
@@ -177,8 +177,7 @@ func TestCache_StoreAndLookup(t *testing.T) {
 	cacheKey := CacheKey(req)
 	outputContent := []byte("fake webp data")
-	err = cache.StoreVariant(
+	err = cache.StoreVariant(cacheKey, bytes.NewReader(outputContent), "image/webp")
 		t.Context(), cacheKey, bytes.NewReader(outputContent), "image/webp")
 	if err != nil {
 		t.Fatalf("StoreVariant() error = %v", err)
 	}
@@ -296,8 +295,7 @@ func TestCache_VariantLookup(t *testing.T) {
 	cacheKey := CacheKey(req)
 	outputContent := []byte("output data")
-	err := cache.StoreVariant(
+	err := cache.StoreVariant(cacheKey, bytes.NewReader(outputContent), "image/webp")
 		t.Context(), cacheKey, bytes.NewReader(outputContent), "image/webp")
 	if err != nil {
 		t.Fatalf("StoreVariant() error = %v", err)
 	}
@@ -346,8 +344,7 @@ func TestCache_GetVariant_ReturnsContentType(t *testing.T) {
 	cacheKey := CacheKey(req)
 	outputContent := []byte("output webp data")
-	err := cache.StoreVariant(
+	err := cache.StoreVariant(cacheKey, bytes.NewReader(outputContent), "image/webp")
 		t.Context(), cacheKey, bytes.NewReader(outputContent), "image/webp")
 	if err != nil {
 		t.Fatalf("StoreVariant() error = %v", err)
 	}
@@ -398,8 +395,7 @@ func TestCache_GetVariant(t *testing.T) {
 	cacheKey := CacheKey(req)
 	outputContent := []byte("the actual output content")
-	err := cache.StoreVariant(
+	err := cache.StoreVariant(cacheKey, bytes.NewReader(outputContent), "image/webp")
 		t.Context(), cacheKey, bytes.NewReader(outputContent), "image/webp")
 	if err != nil {
 		t.Fatalf("StoreVariant() error = %v", err)
 	}
--- a/internal/imgcache/contentlock.go
+++ b/internal/imgcache/contentlock.go
@@ -1,64 +0,0 @@
 package imgcache
 import "sync"
 // contentLock provides per-key mutual exclusion for content-hash keyed
 // operations. StoreSource and evictSourceBlob each hold a content
 // hash's lock for the full duration of their file-plus-accounting-row
 // work, so a store and an eviction racing on identical content bytes
 // (the real SHA-256 content-addressed dedup case, not a contrived one)
 // can never interleave: the unlink of an evicted blob's file can never
 // race the creation of a fresh database row for a concurrently
 // re-stored copy of the same content. Entries are removed once no
 // goroutine holds or is waiting for them, so a long-running process
 // does not accumulate memory proportional to the number of distinct
 // content hashes it has ever seen.
 type contentLock struct {
 	mu      sync.Mutex
 	entries map[string]*contentLockEntry
 }
 // contentLockEntry is one key's exclusion lock plus a count of
 // goroutines currently holding or waiting to acquire it, used to know
 // when it is safe to remove the entry from the map.
 type contentLockEntry struct {
 	mu    sync.Mutex
 	count int
 }
 // newContentLock creates an empty contentLock.
 func newContentLock() *contentLock {
 	return &contentLock{entries: make(map[string]*contentLockEntry)}
 }
 // Lock acquires exclusive access for key, blocking until it is
 // available, and returns a function that releases it. The caller must
 // invoke the returned function exactly once to release the lock.
 func (c *contentLock) Lock(key string) func() {
 	c.mu.Lock()
 	entry, ok := c.entries[key]
 	if !ok {
 		entry = &contentLockEntry{}
 		c.entries[key] = entry
 	}
 	entry.count++
 	c.mu.Unlock()
 	entry.mu.Lock()
 	return func() {
 		entry.mu.Unlock()
 		c.mu.Lock()
 		entry.count--
 		if entry.count == 0 {
 			delete(c.entries, key)
 		}
 		c.mu.Unlock()
 	}
 }
--- a/internal/imgcache/contentlock_internal_test.go
+++ b/internal/imgcache/contentlock_internal_test.go
@@ -1,142 +0,0 @@
 package imgcache
 import (
 	"sync"
 	"sync/atomic"
 	"testing"
 	"time"
 )
 // TestContentLockExcludesSameKey verifies that two goroutines locking
 // the same key never run their critical sections concurrently.
 func TestContentLockExcludesSameKey(t *testing.T) {
 	t.Parallel()
 	lock := newContentLock()
 	var (
 		active  atomic.Int32
 		maxSeen int32
 		wg      sync.WaitGroup
 	)
 	const goroutines = 20
 	wg.Add(goroutines)
 	for range goroutines {
 		go func() {
 			defer wg.Done()
 			unlock := lock.Lock("same-key")
 			defer unlock()
 			n := active.Add(1)
 			for {
 				seen := atomic.LoadInt32(&maxSeen)
 				if n <= seen || atomic.CompareAndSwapInt32(&maxSeen, seen, n) {
 					break
 				}
 			}
 			time.Sleep(time.Millisecond)
 			active.Add(-1)
 		}()
 	}
 	wg.Wait()
 	if maxSeen != 1 {
 		t.Errorf("max concurrent holders of the same key = %d, want 1", maxSeen)
 	}
 }
 // TestContentLockAllowsDifferentKeys verifies that locking distinct
 // keys does not serialize unrelated work: all goroutines must be able
 // to enter their critical sections at once, proven by every one of
 // them reaching the rendezvous point before any is allowed to
 // proceed.
 func TestContentLockAllowsDifferentKeys(t *testing.T) {
 	t.Parallel()
 	lock := newContentLock()
 	const goroutines = 20
 	var (
 		wg      sync.WaitGroup
 		inside  atomic.Int32
 		reached = make(chan struct{}, goroutines)
 	)
 	wg.Add(goroutines)
 	release := make(chan struct{})
 	for i := range goroutines {
 		key := string(rune('a' + i))
 		go func() {
 			defer wg.Done()
 			unlock := lock.Lock(key)
 			defer unlock()
 			inside.Add(1)
 			reached <- struct{}{}
 			<-release
 		}()
 	}
 	// Every goroutine must reach the rendezvous point (i.e. acquire its
 	// own key's lock) without needing any other to release first. If
 	// keys were incorrectly serialized onto one underlying lock, only
 	// one would get here and this would time out.
 	for i := range goroutines {
 		select {
 		case <-reached:
 		case <-time.After(2 * time.Second):
 			t.Fatalf("only %d/%d goroutines locking distinct keys made progress; "+
 				"keys may be incorrectly serialized", i, goroutines)
 		}
 	}
 	if n := inside.Load(); n != goroutines {
 		t.Errorf("goroutines inside their critical section = %d, want %d",
 			n, goroutines)
 	}
 	close(release)
 	wg.Wait()
 }
 // TestContentLockRemovesEntryAfterUnlock verifies that the internal
 // entries map does not grow without bound: once no goroutine holds or
 // awaits a key, its entry is removed.
 func TestContentLockRemovesEntryAfterUnlock(t *testing.T) {
 	t.Parallel()
 	lock := newContentLock()
 	unlock := lock.Lock("k")
 	lock.mu.Lock()
 	if _, ok := lock.entries["k"]; !ok {
 		lock.mu.Unlock()
 		t.Fatal("entry missing while lock is held")
 	}
 	lock.mu.Unlock()
 	unlock()
 	lock.mu.Lock()
 	defer lock.mu.Unlock()
 	if _, ok := lock.entries["k"]; ok {
 		t.Error("entry for key still present after the last holder unlocked")
 	}
 }
--- a/internal/imgcache/eviction.go
+++ b/internal/imgcache/eviction.go
@@ -1,803 +0,0 @@
 package imgcache
 import (
 	"context"
 	"database/sql"
 	"encoding/json"
 	"fmt"
 	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
 	"time"
 )
 // DefaultEvictionInterval is how often the background evictor checks
 // cache usage against the configured limit, in addition to the
 // write-pressure wakeups triggered by stores.
 const DefaultEvictionInterval = 5 * time.Minute
 // evictionBatchSize is how many LRU candidates of each class (variants
 // and source blobs) one eviction pass fetches from the database.
 const evictionBatchSize = 100
 // staleTempFileAge is how old an orphaned temp file (left behind by a
 // crashed write) must be before reconciliation removes it. Fresh temp
 // files may still belong to an in-flight store.
 const staleTempFileAge = time.Hour
 // sqliteTimestampLayout matches SQLite's CURRENT_TIMESTAMP format, so
 // timestamps written by reconciliation order correctly against ones
 // written by the hot path.
 const sqliteTimestampLayout = "2006-01-02 15:04:05"
 // tempFilePrefix is the prefix os.CreateTemp uses for in-flight cache
 // writes (".tmp-*" patterns in the storage layer).
 const tempFilePrefix = ".tmp-"
 // variantMetaSuffix is the sidecar suffix VariantStorage writes next
 // to each variant file.
 const variantMetaSuffix = ".meta"
 // fallbackContentType is recorded when a reconciled variant file has
 // no readable .meta sidecar.
 const fallbackContentType = "application/octet-stream"
 // UsageBytes returns the total number of bytes of cache content
 // tracked in the database (source content blobs plus processed
 // variants). It never scans the cache directories.
 func (c *Cache) UsageBytes(ctx context.Context) (int64, error) {
 	if c.disabled {
 		return 0, nil
 	}
 	var total int64
 	err := c.db.QueryRowContext(ctx, `
 		SELECT (SELECT COALESCE(SUM(size_bytes), 0) FROM source_content)
 		     + (SELECT COALESCE(SUM(size_bytes), 0) FROM variant_content)
 	`).Scan(&total)
 	if err != nil {
 		return 0, fmt.Errorf("failed to compute cache usage: %w", err)
 	}
 	return total, nil
 }
 // evictionCandidate is one LRU eviction victim candidate: either a
 // processed variant (isVariant true, identified by cacheKey) or a
 // source content blob (identified by contentHash).
 type evictionCandidate struct {
 	isVariant      bool
 	cacheKey       VariantKey
 	contentHash    ContentHash
 	sizeBytes      int64
 	lastAccessedAt string
 }
 // EvictToLimit evicts least-recently-used cache entries until total
 // tracked usage is at or below the configured MaxBytes limit. It is a
 // no-op when the cache is disabled or no limit is configured.
 func (c *Cache) EvictToLimit(ctx context.Context) error {
 	if c.disabled || c.config.MaxBytes <= 0 {
 		return nil
 	}
 	for {
 		usage, err := c.UsageBytes(ctx)
 		if err != nil {
 			return err
 		}
 		if usage <= c.config.MaxBytes {
 			return nil
 		}
 		freed, err := c.evictBatch(ctx, usage-c.config.MaxBytes)
 		if err != nil {
 			return err
 		}
 		if freed == 0 {
 			c.log.Warn("cache eviction made no progress",
 				"usage_bytes", usage,
 				"cache_max_bytes", c.config.MaxBytes,
 			)
 			return nil
 		}
 		c.log.Info("evicted cache content",
 			"freed_bytes", freed,
 			"usage_bytes", usage-freed,
 			"cache_max_bytes", c.config.MaxBytes,
 		)
 	}
 }
 // evictBatch fetches one batch of LRU candidates across variants and
 // source blobs and evicts them oldest-first until excessBytes are
 // freed or the batch is exhausted. It returns the bytes freed.
 func (c *Cache) evictBatch(ctx context.Context, excessBytes int64) (int64, error) {
 	candidates, err := c.evictionCandidates(ctx)
 	if err != nil {
 		return 0, err
 	}
 	var freed int64
 	for _, candidate := range candidates {
 		if freed >= excessBytes {
 			break
 		}
 		err := c.evictCandidate(ctx, candidate)
 		if err != nil {
 			c.log.Warn("failed to evict cache entry",
 				"cache_key", candidate.cacheKey,
 				"content_hash", candidate.contentHash,
 				"error", err,
 			)
 			continue
 		}
 		freed += candidate.sizeBytes
 	}
 	return freed, nil
 }
 // evictCandidate removes a single eviction victim.
 func (c *Cache) evictCandidate(ctx context.Context, candidate evictionCandidate) error {
 	if candidate.isVariant {
 		return c.evictVariant(ctx, candidate.cacheKey)
 	}
 	return c.evictSourceBlob(ctx, candidate.contentHash)
 }
 // evictionCandidates returns up to evictionBatchSize variants and
 // evictionBatchSize source blobs, merged into a single list ordered by
 // last access time (oldest first).
 func (c *Cache) evictionCandidates(ctx context.Context) ([]evictionCandidate, error) {
 	variants, err := c.variantCandidates(ctx)
 	if err != nil {
 		return nil, err
 	}
 	sources, err := c.sourceCandidates(ctx)
 	if err != nil {
 		return nil, err
 	}
 	// Merge the two lists, each already sorted oldest-first. SQLite
 	// CURRENT_TIMESTAMP strings compare correctly lexicographically.
 	merged := make([]evictionCandidate, 0, len(variants)+len(sources))
 	for len(variants) > 0 && len(sources) > 0 {
 		if variants[0].lastAccessedAt <= sources[0].lastAccessedAt {
 			merged = append(merged, variants[0])
 			variants = variants[1:]
 		} else {
 			merged = append(merged, sources[0])
 			sources = sources[1:]
 		}
 	}
 	merged = append(merged, variants...)
 	merged = append(merged, sources...)
 	return merged, nil
 }
 // variantCandidates returns the least recently used variants.
 func (c *Cache) variantCandidates(ctx context.Context) ([]evictionCandidate, error) {
 	rows, err := c.db.QueryContext(ctx, `
 		SELECT cache_key, size_bytes, last_accessed_at
 		FROM variant_content
 		ORDER BY last_accessed_at ASC, cache_key ASC
 		LIMIT ?
 	`, evictionBatchSize)
 	if err != nil {
 		return nil, fmt.Errorf("failed to query variant eviction candidates: %w", err)
 	}
 	defer func() { _ = rows.Close() }()
 	var candidates []evictionCandidate
 	for rows.Next() {
 		candidate := evictionCandidate{isVariant: true}
 		var key string
 		err := rows.Scan(&key, &candidate.sizeBytes, &candidate.lastAccessedAt)
 		if err != nil {
 			return nil, fmt.Errorf("failed to scan variant candidate: %w", err)
 		}
 		candidate.cacheKey = VariantKey(key)
 		candidates = append(candidates, candidate)
 	}
 	err = rows.Err()
 	if err != nil {
 		return nil, fmt.Errorf("variant candidate iteration failed: %w", err)
 	}
 	return candidates, nil
 }
 // sourceCandidates returns the least recently used source blobs. Rows
 // written before the LRU column existed fall back to fetched_at.
 func (c *Cache) sourceCandidates(ctx context.Context) ([]evictionCandidate, error) {
 	rows, err := c.db.QueryContext(ctx, `
 		SELECT content_hash, size_bytes,
 		       COALESCE(last_accessed_at, fetched_at, '1970-01-01 00:00:00') AS lru
 		FROM source_content
 		ORDER BY lru ASC, content_hash ASC
 		LIMIT ?
 	`, evictionBatchSize)
 	if err != nil {
 		return nil, fmt.Errorf("failed to query source eviction candidates: %w", err)
 	}
 	defer func() { _ = rows.Close() }()
 	var candidates []evictionCandidate
 	for rows.Next() {
 		var candidate evictionCandidate
 		var hash string
 		err := rows.Scan(&hash, &candidate.sizeBytes, &candidate.lastAccessedAt)
 		if err != nil {
 			return nil, fmt.Errorf("failed to scan source candidate: %w", err)
 		}
 		candidate.contentHash = ContentHash(hash)
 		candidates = append(candidates, candidate)
 	}
 	err = rows.Err()
 	if err != nil {
 		return nil, fmt.Errorf("source candidate iteration failed: %w", err)
 	}
 	return candidates, nil
 }
 // evictVariant removes one variant: accounting row first, then the
 // content and .meta files, so the database never references a deleted
 // file.
 func (c *Cache) evictVariant(ctx context.Context, cacheKey VariantKey) error {
 	_, err := c.db.ExecContext(ctx,
 		`DELETE FROM variant_content WHERE cache_key = ?`, string(cacheKey))
 	if err != nil {
 		return fmt.Errorf("failed to delete variant accounting row: %w", err)
 	}
 	err = c.variants.DeleteWithMeta(cacheKey)
 	if err != nil {
 		return err
 	}
 	return nil
 }
 // sourceReference identifies one source_metadata row's JSON sidecar.
 type sourceReference struct {
 	host     string
 	pathHash PathHash
 }
 // evictSourceBlob removes one source content blob. All source_metadata
 // rows referencing the blob are deleted together with its
 // source_content row in a single transaction BEFORE the file is
 // unlinked: a blob referenced by multiple source paths is only ever
 // removed together with all of its references, and database rows never
 // point at deleted files. The JSON metadata sidecars for the removed
 // rows are deleted afterwards.
 //
 // The whole operation holds the content hash's lock (the same one
 // StoreSource holds for its full store), so a concurrent store of
 // identical content bytes can never observe the file gone but a row
 // still present, or insert a fresh row between this transaction's
 // commit and the file unlink below: it either runs entirely before
 // this eviction starts, or is blocked until this eviction (row
 // deletion and unlink together) has fully completed.
 func (c *Cache) evictSourceBlob(ctx context.Context, contentHash ContentHash) error {
 	unlock := c.contentLocks.Lock(string(contentHash))
 	defer unlock()
 	references, err := c.sourceReferences(ctx, contentHash)
 	if err != nil {
 		return err
 	}
 	tx, err := c.db.BeginTx(ctx, nil)
 	if err != nil {
 		return fmt.Errorf("failed to begin eviction transaction: %w", err)
 	}
 	defer func() { _ = tx.Rollback() }()
 	_, err = tx.ExecContext(ctx,
 		`DELETE FROM source_metadata WHERE content_hash = ?`, string(contentHash))
 	if err != nil {
 		return fmt.Errorf("failed to delete source metadata rows: %w", err)
 	}
 	_, err = tx.ExecContext(ctx,
 		`DELETE FROM source_content WHERE content_hash = ?`, string(contentHash))
 	if err != nil {
 		return fmt.Errorf("failed to delete source content row: %w", err)
 	}
 	err = tx.Commit()
 	if err != nil {
 		return fmt.Errorf("failed to commit eviction transaction: %w", err)
 	}
 	if c.evictSourceBlobTestHook != nil {
 		c.evictSourceBlobTestHook(contentHash)
 	}
 	// Only after the rows are gone may the files be removed.
 	for _, reference := range references {
 		err := c.srcMetadata.Delete(reference.host, reference.pathHash)
 		if err != nil {
 			c.log.Warn("failed to delete metadata sidecar",
 				"host", reference.host, "path_hash", reference.pathHash, "error", err)
 		}
 	}
 	err = c.srcContent.Delete(contentHash)
 	if err != nil {
 		return err
 	}
 	return nil
 }
 // sourceReferences lists the metadata sidecar locations of every
 // source_metadata row referencing the given blob.
 func (c *Cache) sourceReferences(
 	ctx context.Context, contentHash ContentHash,
 ) ([]sourceReference, error) {
 	rows, err := c.db.QueryContext(ctx, `
 		SELECT source_host, path_hash FROM source_metadata WHERE content_hash = ?
 	`, string(contentHash))
 	if err != nil {
 		return nil, fmt.Errorf("failed to query source references: %w", err)
 	}
 	defer func() { _ = rows.Close() }()
 	var references []sourceReference
 	for rows.Next() {
 		var reference sourceReference
 		var pathHash string
 		err := rows.Scan(&reference.host, &pathHash)
 		if err != nil {
 			return nil, fmt.Errorf("failed to scan source reference: %w", err)
 		}
 		reference.pathHash = PathHash(pathHash)
 		references = append(references, reference)
 	}
 	err = rows.Err()
 	if err != nil {
 		return nil, fmt.Errorf("source reference iteration failed: %w", err)
 	}
 	return references, nil
 }
 // notifyWritePressure wakes the background evictor after a store, so
 // eviction under write pressure happens promptly without blocking the
 // storing request. The notification channel has capacity one and drops
 // when a wakeup is already pending.
 func (c *Cache) notifyWritePressure() {
 	if c.disabled || c.config.MaxBytes <= 0 {
 		return
 	}
 	select {
 	case c.evictionPressure <- struct{}{}:
 	default:
 	}
 }
 // StartEviction launches the background eviction goroutine, which
 // reconciles the database accounting with the cache directories at
 // startup and again on every periodic tick thereafter, and evicts to
 // the configured limit on the given periodic interval and on
 // write-pressure notifications. It is a no-op on a disabled cache or
 // when already started.
 func (c *Cache) StartEviction(interval time.Duration) {
 	if c.disabled || c.evictionStarted {
 		return
 	}
 	c.evictionStarted = true
 	go c.evictionLoop(interval)
 }
 // StopEviction stops the background eviction goroutine and waits for
 // it to exit. It is safe to call when eviction was never started, and
 // safe to call more than once.
 func (c *Cache) StopEviction() {
 	if !c.evictionStarted {
 		return
 	}
 	c.evictionStopOnce.Do(func() {
 		close(c.evictionStop)
 		<-c.evictionDone
 	})
 }
 // evictionLoop is the body of the background eviction goroutine.
 func (c *Cache) evictionLoop(interval time.Duration) {
 	defer close(c.evictionDone)
 	ctx := context.Background()
 	c.runReconciliationPass(ctx)
 	c.runEvictionPass(ctx)
 	ticker := time.NewTicker(interval)
 	defer ticker.Stop()
 	for {
 		select {
 		case <-c.evictionStop:
 			return
 		case <-ticker.C:
 			// Reconciliation walks the cache directories, so it only
 			// runs on the periodic ticker rather than on every
 			// write-pressure wakeup, keeping it off the per-store hot
 			// path. Reusing the eviction interval itself (rather than a
 			// separate, longer one) is a deliberate choice: it is the
 			// simplest option that still bounds how long a store's
 			// best-effort accounting insert can stay silently
 			// unaccounted for to one interval, on a process that is
 			// already running this loop regardless.
 			c.runReconciliationPass(ctx)
 		case <-c.evictionPressure:
 		}
 		c.runEvictionPass(ctx)
 	}
 }
 // runEvictionPass runs one eviction pass, logging failures instead of
 // propagating them (the loop must keep running).
 func (c *Cache) runEvictionPass(ctx context.Context) {
 	err := c.EvictToLimit(ctx)
 	if err != nil {
 		c.log.Warn("cache eviction pass failed", "error", err)
 	}
 }
 // runReconciliationPass runs one reconciliation pass, logging failures
 // instead of propagating them (the loop must keep running).
 func (c *Cache) runReconciliationPass(ctx context.Context) {
 	err := c.reconcileAccounting(ctx)
 	if err != nil {
 		c.log.Warn("cache accounting reconciliation failed", "error", err)
 	}
 }
 // reconcileAccounting synchronizes the database size accounting with
 // the actual contents of the cache directories. It runs at startup and
 // again on every periodic eviction tick thereafter, off the request
 // hot path: it adopts variant files that predate the accounting table
 // (or whose accounting insert failed, e.g. StoreVariant's best-effort
 // insert under transient DB contention), drops accounting rows whose
 // files are missing, removes source blob files the database does not
 // know (and rows whose files are gone), and sweeps stale temp files
 // left behind by crashed writes. Running it periodically, not just
 // once, bounds how long such drift can accumulate unaccounted for on a
 // long-running process to one eviction interval.
 func (c *Cache) reconcileAccounting(ctx context.Context) error {
 	if c.disabled {
 		return nil
 	}
 	err := c.reconcileVariantFiles(ctx)
 	if err != nil {
 		return err
 	}
 	err = c.reconcileVariantRows(ctx)
 	if err != nil {
 		return err
 	}
 	err = c.reconcileSourceFiles(ctx)
 	if err != nil {
 		return err
 	}
 	err = c.reconcileSourceRows(ctx)
 	if err != nil {
 		return err
 	}
 	return nil
 }
 // reconcileVariantFiles walks the variant storage directory, adopting
 // files without accounting rows and sweeping stale temp files.
 func (c *Cache) reconcileVariantFiles(ctx context.Context) error {
 	return filepath.WalkDir(
 		c.variants.baseDir,
 		func(path string, entry fs.DirEntry, err error) error {
 			if err != nil || entry.IsDir() {
 				return err
 			}
 			name := entry.Name()
 			if strings.HasPrefix(name, tempFilePrefix) {
 				c.sweepStaleTempFile(path, entry)
 				return nil
 			}
 			if strings.HasSuffix(name, variantMetaSuffix) {
 				return nil
 			}
 			return c.adoptVariantFile(ctx, path, entry, VariantKey(name))
 		},
 	)
 }
 // adoptVariantFile inserts an accounting row for a variant file that
 // has none, using the file's size and modification time.
 func (c *Cache) adoptVariantFile(
 	ctx context.Context, path string, entry fs.DirEntry, cacheKey VariantKey,
 ) error {
 	var rowExists int
 	err := c.db.QueryRowContext(ctx,
 		`SELECT COUNT(*) FROM variant_content WHERE cache_key = ?`, string(cacheKey),
 	).Scan(&rowExists)
 	if err != nil {
 		return fmt.Errorf("failed to check variant accounting row: %w", err)
 	}
 	if rowExists > 0 {
 		return nil
 	}
 	info, err := entry.Info()
 	if err != nil {
 		return fmt.Errorf("failed to stat variant file: %w", err)
 	}
 	modTime := info.ModTime().UTC().Format(sqliteTimestampLayout)
 	contentType := c.variantContentTypeFromSidecar(path)
 	_, err = c.db.ExecContext(ctx, `
 		INSERT INTO variant_content
 			(cache_key, size_bytes, content_type, created_at, last_accessed_at)
 		VALUES (?, ?, ?, ?, ?)
 	`, string(cacheKey), info.Size(), contentType, modTime, modTime)
 	if err != nil {
 		return fmt.Errorf("failed to adopt variant file into accounting: %w", err)
 	}
 	c.log.Info("adopted untracked variant file into size accounting",
 		"cache_key", cacheKey, "size_bytes", info.Size())
 	return nil
 }
 // variantContentTypeFromSidecar reads the content type from a variant
 // .meta sidecar, falling back to application/octet-stream.
 func (c *Cache) variantContentTypeFromSidecar(variantPath string) string {
 	//nolint:gosec // path from cache walk
 	metaData, err := os.ReadFile(variantPath + variantMetaSuffix)
 	if err != nil {
 		return fallbackContentType
 	}
 	var meta VariantMeta
 	if json.Unmarshal(metaData, &meta) != nil || meta.ContentType == "" {
 		return fallbackContentType
 	}
 	return meta.ContentType
 }
 // reconcileVariantRows drops accounting rows whose variant files are
 // missing, so the database never references deleted content.
 func (c *Cache) reconcileVariantRows(ctx context.Context) error {
 	keys, err := c.allVariantKeys(ctx)
 	if err != nil {
 		return err
 	}
 	for _, key := range keys {
 		if c.variants.Exists(key) {
 			continue
 		}
 		_, err := c.db.ExecContext(ctx,
 			`DELETE FROM variant_content WHERE cache_key = ?`, string(key))
 		if err != nil {
 			return fmt.Errorf("failed to drop stale variant accounting row: %w", err)
 		}
 		c.log.Info("dropped accounting row for missing variant file", "cache_key", key)
 	}
 	return nil
 }
 // allVariantKeys returns every tracked variant cache key.
 func (c *Cache) allVariantKeys(ctx context.Context) ([]VariantKey, error) {
 	return queryStringColumn[VariantKey](ctx, c.db,
 		`SELECT cache_key FROM variant_content`, "variant keys", "variant key")
 }
 // queryStringColumn runs a single-column query and returns the column
 // values as T. plural names the set for the query and scan failure
 // messages; singular names one row for the scan and iteration failure
 // messages.
 func queryStringColumn[T ~string](
 	ctx context.Context, db *sql.DB, query, plural, singular string,
 ) ([]T, error) {
 	rows, err := db.QueryContext(ctx, query)
 	if err != nil {
 		return nil, fmt.Errorf("failed to query %s: %w", plural, err)
 	}
 	defer func() { _ = rows.Close() }()
 	var values []T
 	for rows.Next() {
 		var value string
 		err := rows.Scan(&value)
 		if err != nil {
 			return nil, fmt.Errorf("failed to scan %s: %w", singular, err)
 		}
 		values = append(values, T(value))
 	}
 	err = rows.Err()
 	if err != nil {
 		return nil, fmt.Errorf("%s iteration failed: %w", singular, err)
 	}
 	return values, nil
 }
 // reconcileSourceFiles walks the source content directory, removing
 // blob files the database does not track (they are unreachable: source
 // lookups always go through source_metadata) and sweeping stale temp
 // files.
 func (c *Cache) reconcileSourceFiles(ctx context.Context) error {
 	return filepath.WalkDir(
 		c.srcContent.baseDir,
 		func(path string, entry fs.DirEntry, err error) error {
 			if err != nil || entry.IsDir() {
 				return err
 			}
 			name := entry.Name()
 			if strings.HasPrefix(name, tempFilePrefix) {
 				c.sweepStaleTempFile(path, entry)
 				return nil
 			}
 			return c.removeUntrackedSourceFile(ctx, path, ContentHash(name))
 		},
 	)
 }
 // removeUntrackedSourceFile deletes a source blob file that has no
 // source_content row. Any source_metadata rows referencing the hash
 // are removed first so no row ever points at a deleted file.
 func (c *Cache) removeUntrackedSourceFile(
 	ctx context.Context, path string, contentHash ContentHash,
 ) error {
 	var rowExists int
 	err := c.db.QueryRowContext(ctx,
 		`SELECT COUNT(*) FROM source_content WHERE content_hash = ?`, string(contentHash),
 	).Scan(&rowExists)
 	if err != nil {
 		return fmt.Errorf("failed to check source content row: %w", err)
 	}
 	if rowExists > 0 {
 		return nil
 	}
 	_, err = c.db.ExecContext(ctx,
 		`DELETE FROM source_metadata WHERE content_hash = ?`, string(contentHash))
 	if err != nil {
 		return fmt.Errorf("failed to delete metadata rows for untracked blob: %w", err)
 	}
 	err = os.Remove(path)
 	if err != nil && !os.IsNotExist(err) {
 		return fmt.Errorf("failed to remove untracked source file: %w", err)
 	}
 	c.log.Info("removed untracked source content file", "content_hash", contentHash)
 	return nil
 }
 // reconcileSourceRows removes source_content rows (and their metadata
 // references and sidecars) whose blob files are missing on disk.
 func (c *Cache) reconcileSourceRows(ctx context.Context) error {
 	hashes, err := c.allSourceContentHashes(ctx)
 	if err != nil {
 		return err
 	}
 	for _, hash := range hashes {
 		if c.srcContent.Exists(hash) {
 			continue
 		}
 		// The blob file is already gone; evictSourceBlob removes the
 		// rows and sidecars and tolerates the missing file.
 		err := c.evictSourceBlob(ctx, hash)
 		if err != nil {
 			return err
 		}
 		c.log.Info("dropped rows for missing source content file", "content_hash", hash)
 	}
 	return nil
 }
 // allSourceContentHashes returns every tracked source content hash.
 func (c *Cache) allSourceContentHashes(ctx context.Context) ([]ContentHash, error) {
 	return queryStringColumn[ContentHash](ctx, c.db,
 		`SELECT content_hash FROM source_content`,
 		"source content hashes", "content hash")
 }
 // sweepStaleTempFile removes a temp file left behind by a crashed
 // write once it is old enough that no in-flight store can own it.
 func (c *Cache) sweepStaleTempFile(path string, entry fs.DirEntry) {
 	info, err := entry.Info()
 	if err != nil {
 		return
 	}
 	if time.Since(info.ModTime()) < staleTempFileAge {
 		return
 	}
 	err = os.Remove(path)
 	if err != nil && !os.IsNotExist(err) {
 		c.log.Warn("failed to remove stale temp file", "path", path, "error", err)
 		return
 	}
 	c.log.Info("removed stale temp file", "path", path)
 }
--- a/internal/imgcache/eviction_internal_test.go
+++ b/internal/imgcache/eviction_internal_test.go
@@ -1,985 +0,0 @@
 package imgcache
 import (
 	"bytes"
 	"context"
 	"database/sql"
 	"io/fs"
 	"os"
 	"path/filepath"
 	"testing"
 	"time"
 	_ "modernc.org/sqlite"
 	"sneak.berlin/go/pixa/internal/database"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
 )
 // sqliteTimestampFormat matches the format SQLite's CURRENT_TIMESTAMP
 // produces, so injected timestamps compare correctly against ones the
 // implementation writes.
 const sqliteTimestampFormat = "2006-01-02 15:04:05"
 // testVariantKeyOne through testVariantKeyFour are the variant cache
 // keys reused across the eviction tests, in the order the tests store
 // them.
 const (
 	testVariantKeyOne   VariantKey = "aabbccdd0001"
 	testVariantKeyTwo   VariantKey = "aabbccdd0002"
 	testVariantKeyThree VariantKey = "aabbccdd0003"
 	testVariantKeyFour  VariantKey = "aabbccdd0004"
 )
 // evictionTestDB creates an in-memory SQLite database with the real
 // production schema, limited to a single connection so the background
 // eviction goroutine shares the same in-memory database as the test.
 func evictionTestDB(t *testing.T) *sql.DB {
 	t.Helper()
 	db, err := sql.Open("sqlite", ":memory:")
 	if err != nil {
 		t.Fatalf("failed to open test db: %v", err)
 	}
 	db.SetMaxOpenConns(1)
 	err = database.ApplyMigrations(context.Background(), db, nil)
 	if err != nil {
 		t.Fatalf("failed to apply migrations: %v", err)
 	}
 	t.Cleanup(func() { _ = db.Close() })
 	return db
 }
 // newEvictionTestCache creates a Cache backed by a temp directory and
 // an in-memory database, with the given size limit.
 func newEvictionTestCache(t *testing.T, maxBytes int64) (*Cache, string) {
 	t.Helper()
 	tmpDir := t.TempDir()
 	db := evictionTestDB(t)
 	// maxBytes zero mirrors the production mapping of
 	// cache_max_bytes: 0 (handlers sets DisableDiskCache); at the
 	// CacheConfig layer itself a zero MaxBytes means "no limit" for
 	// backwards compatibility with existing fixtures.
 	cache, err := NewCache(db, CacheConfig{
 		StateDir:         tmpDir,
 		CacheTTL:         time.Hour,
 		NegativeTTL:      5 * time.Minute,
 		MaxBytes:         maxBytes,
 		DisableDiskCache: maxBytes == 0,
 	})
 	if err != nil {
 		t.Fatalf("failed to create cache: %v", err)
 	}
 	return cache, tmpDir
 }
 // storeEvictionTestSource stores content as a fetched source for
 // host/path and returns the resulting content hash.
 func storeEvictionTestSource(
 	t *testing.T, cache *Cache, host, path string, content []byte,
 ) ContentHash {
 	t.Helper()
 	req := &ImageRequest{
 		SourceHost: host,
 		SourcePath: path,
 		Format:     FormatJPEG,
 		Quality:    85,
 		FitMode:    FitCover,
 	}
 	result := &httpfetcher.FetchResult{
 		StatusCode:    200,
 		ContentType:   testContentTypeJPEG,
 		ContentLength: int64(len(content)),
 		Headers: map[string][]string{
 			testHeaderContentType: {testContentTypeJPEG},
 		},
 	}
 	hash, err := cache.StoreSource(
 		context.Background(), req, bytes.NewReader(content), result,
 	)
 	if err != nil {
 		t.Fatalf("StoreSource(%s%s) failed: %v", host, path, err)
 	}
 	return hash
 }
 // storeEvictionTestVariant stores content as a processed variant under
 // the given cache key.
 func storeEvictionTestVariant(
 	t *testing.T, cache *Cache, key VariantKey, content []byte,
 ) {
 	t.Helper()
 	err := cache.StoreVariant(t.Context(), key, bytes.NewReader(content), "image/webp")
 	if err != nil {
 		t.Fatalf("StoreVariant(%s) failed: %v", key, err)
 	}
 }
 // setVariantLastAccessed backdates the last access time of a tracked
 // variant, to make LRU ordering deterministic in tests.
 func setVariantLastAccessed(
 	t *testing.T, cache *Cache, key VariantKey, when time.Time,
 ) {
 	t.Helper()
 	res, err := cache.db.ExecContext(t.Context(),
 		`UPDATE variant_content SET last_accessed_at = ? WHERE cache_key = ?`,
 		when.UTC().Format(sqliteTimestampFormat), string(key),
 	)
 	if err != nil {
 		t.Fatalf("failed to set variant last_accessed_at: %v", err)
 	}
 	affected, err := res.RowsAffected()
 	if err != nil {
 		t.Fatalf("failed to read affected rows: %v", err)
 	}
 	if affected != 1 {
 		t.Fatalf("variant %s has no accounting row (affected=%d); "+
 			"stores must track variants in the database", key, affected)
 	}
 }
 // setSourceLastAccessed backdates the last access time of a tracked
 // source content blob.
 func setSourceLastAccessed(
 	t *testing.T, cache *Cache, hash ContentHash, when time.Time,
 ) {
 	t.Helper()
 	res, err := cache.db.ExecContext(t.Context(),
 		`UPDATE source_content SET last_accessed_at = ? WHERE content_hash = ?`,
 		when.UTC().Format(sqliteTimestampFormat), string(hash),
 	)
 	if err != nil {
 		t.Fatalf("failed to set source last_accessed_at: %v", err)
 	}
 	affected, err := res.RowsAffected()
 	if err != nil {
 		t.Fatalf("failed to read affected rows: %v", err)
 	}
 	if affected != 1 {
 		t.Fatalf("source %s has no accounting row (affected=%d)", hash, affected)
 	}
 }
 // countRows returns the number of rows the given query yields.
 func countRows(t *testing.T, cache *Cache, query string, args ...any) int {
 	t.Helper()
 	var n int
 	err := cache.db.QueryRowContext(t.Context(), query, args...).Scan(&n)
 	if err != nil {
 		t.Fatalf("count query %q failed: %v", query, err)
 	}
 	return n
 }
 // assertNoDanglingReferences verifies the core eviction invariant:
 // every database row that references cache content on disk points at a
 // file that actually exists.
 func assertNoDanglingReferences(t *testing.T, cache *Cache) {
 	t.Helper()
 	rows, err := cache.db.QueryContext(t.Context(),
 		`SELECT content_hash FROM source_metadata
 		 WHERE content_hash IS NOT NULL AND content_hash != ''`,
 	)
 	if err != nil {
 		t.Fatalf("failed to query source_metadata: %v", err)
 	}
 	defer func() { _ = rows.Close() }()
 	for rows.Next() {
 		var hash string
 		err := rows.Scan(&hash)
 		if err != nil {
 			t.Fatalf("failed to scan content_hash: %v", err)
 		}
 		if !cache.srcContent.Exists(ContentHash(hash)) {
 			t.Errorf("source_metadata references content %s but the file is missing",
 				hash)
 		}
 	}
 	err = rows.Err()
 	if err != nil {
 		t.Fatalf("source_metadata iteration failed: %v", err)
 	}
 	variantRows, err := cache.db.QueryContext(t.Context(),
 		`SELECT cache_key FROM variant_content`)
 	if err != nil {
 		t.Fatalf("failed to query variant_content: %v", err)
 	}
 	defer func() { _ = variantRows.Close() }()
 	for variantRows.Next() {
 		var key string
 		err := variantRows.Scan(&key)
 		if err != nil {
 			t.Fatalf("failed to scan cache_key: %v", err)
 		}
 		if !cache.variants.Exists(VariantKey(key)) {
 			t.Errorf("variant_content references key %s but the file is missing", key)
 		}
 	}
 	err = variantRows.Err()
 	if err != nil {
 		t.Fatalf("variant_content iteration failed: %v", err)
 	}
 }
 // waitForUsageAtOrBelow polls UsageBytes until it reaches limit or the
 // timeout expires, returning the last observed usage.
 func waitForUsageAtOrBelow(
 	t *testing.T, cache *Cache, limit int64, timeout time.Duration,
 ) int64 {
 	t.Helper()
 	deadline := time.Now().Add(timeout)
 	var usage int64
 	for time.Now().Before(deadline) {
 		var err error
 		usage, err = cache.UsageBytes(context.Background())
 		if err != nil {
 			t.Fatalf("UsageBytes failed: %v", err)
 		}
 		if usage <= limit {
 			return usage
 		}
 		time.Sleep(25 * time.Millisecond)
 	}
 	return usage
 }
 func TestUsageBytesAccountsSourceAndVariantBytes(t *testing.T) {
 	t.Parallel()
 	cache, _ := newEvictionTestCache(t, 1<<30)
 	storeEvictionTestSource(t, cache, "src.example.com", "/a.jpg",
 		bytes.Repeat([]byte{0xAA}, 1000))
 	storeEvictionTestSource(t, cache, "src.example.com", "/b.jpg",
 		bytes.Repeat([]byte{0xAB}, 2000))
 	storeEvictionTestVariant(t, cache, testVariantKeyOne,
 		bytes.Repeat([]byte{0xAC}, 500))
 	storeEvictionTestVariant(t, cache, testVariantKeyTwo,
 		bytes.Repeat([]byte{0xAD}, 250))
 	usage, err := cache.UsageBytes(context.Background())
 	if err != nil {
 		t.Fatalf("UsageBytes failed: %v", err)
 	}
 	if usage != 3750 {
 		t.Errorf("UsageBytes = %d, want 3750 (1000+2000+500+250)", usage)
 	}
 }
 func TestUsageBytesCountsMultiReferencedBlobOnce(t *testing.T) {
 	t.Parallel()
 	cache, _ := newEvictionTestCache(t, 1<<30)
 	content := bytes.Repeat([]byte{0xCC}, 1200)
 	hashOne := storeEvictionTestSource(t, cache,
 		"src.example.com", "/one.jpg", content)
 	hashTwo := storeEvictionTestSource(t, cache,
 		"src.example.com", "/two.jpg", content)
 	if hashOne != hashTwo {
 		t.Fatalf("identical content produced different hashes: %s vs %s",
 			hashOne, hashTwo)
 	}
 	usage, err := cache.UsageBytes(context.Background())
 	if err != nil {
 		t.Fatalf("UsageBytes failed: %v", err)
 	}
 	if usage != 1200 {
 		t.Errorf("UsageBytes = %d, want 1200 (deduplicated blob counted once)", usage)
 	}
 }
 func TestEvictToLimitEvictsLeastRecentlyUsedFirst(t *testing.T) {
 	t.Parallel()
 	const limit = 3000
 	cache, _ := newEvictionTestCache(t, limit)
 	now := time.Now()
 	keys := []VariantKey{
 		testVariantKeyOne, testVariantKeyTwo,
 		testVariantKeyThree, testVariantKeyFour,
 	}
 	fills := []byte{0x01, 0x02, 0x03, 0x04}
 	ages := []time.Duration{4 * time.Hour, 3 * time.Hour, 2 * time.Hour, 1 * time.Hour}
 	for i, key := range keys {
 		storeEvictionTestVariant(t, cache, key, bytes.Repeat([]byte{fills[i]}, 1000))
 		setVariantLastAccessed(t, cache, key, now.Add(-ages[i]))
 	}
 	err := cache.EvictToLimit(context.Background())
 	if err != nil {
 		t.Fatalf("EvictToLimit failed: %v", err)
 	}
 	usage, err := cache.UsageBytes(context.Background())
 	if err != nil {
 		t.Fatalf("UsageBytes failed: %v", err)
 	}
 	if usage > limit {
 		t.Errorf("usage after eviction = %d, want <= %d", usage, limit)
 	}
 	if cache.variants.Exists(keys[0]) {
 		t.Errorf("least recently used variant %s must be evicted", keys[0])
 	}
 	if n := countRows(t, cache,
 		`SELECT COUNT(*) FROM variant_content WHERE cache_key = ?`, string(keys[0]),
 	); n != 0 {
 		t.Errorf("evicted variant %s still has %d accounting rows", keys[0], n)
 	}
 	for _, key := range keys[1:] {
 		if !cache.variants.Exists(key) {
 			t.Errorf("more recently used variant %s must survive eviction", key)
 		}
 	}
 	assertNoDanglingReferences(t, cache)
 }
 func TestEvictionRemovesMultiReferencedBlobTogetherWithAllReferences(t *testing.T) {
 	t.Parallel()
 	const limit = 1000
 	cache, _ := newEvictionTestCache(t, limit)
 	now := time.Now()
 	// One 800-byte blob referenced by two source paths.
 	sharedContent := bytes.Repeat([]byte{0xDD}, 800)
 	sharedHash := storeEvictionTestSource(t, cache,
 		"src.example.com", "/a.jpg", sharedContent)
 	h := storeEvictionTestSource(t, cache,
 		"src.example.com", "/b.jpg", sharedContent)
 	if h != sharedHash {
 		t.Fatalf("identical content produced different hashes: %s vs %s",
 			h, sharedHash)
 	}
 	// A newer 600-byte blob referenced by one source path.
 	recentHash := storeEvictionTestSource(t, cache, "src.example.com", "/c.jpg",
 		bytes.Repeat([]byte{0xEE}, 600))
 	setSourceLastAccessed(t, cache, sharedHash, now.Add(-2*time.Hour))
 	setSourceLastAccessed(t, cache, recentHash, now.Add(-time.Minute))
 	err := cache.EvictToLimit(context.Background())
 	if err != nil {
 		t.Fatalf("EvictToLimit failed: %v", err)
 	}
 	usage, err := cache.UsageBytes(context.Background())
 	if err != nil {
 		t.Fatalf("UsageBytes failed: %v", err)
 	}
 	if usage > limit {
 		t.Errorf("usage after eviction = %d, want <= %d", usage, limit)
 	}
 	// The multi-referenced blob must be gone from disk, from
 	// source_content, and from BOTH source_metadata rows: references
 	// are removed together with the blob, never left dangling.
 	if cache.srcContent.Exists(sharedHash) {
 		t.Errorf("evicted blob %s still exists on disk", sharedHash)
 	}
 	if n := countRows(t, cache,
 		`SELECT COUNT(*) FROM source_content WHERE content_hash = ?`, string(sharedHash),
 	); n != 0 {
 		t.Errorf("evicted blob %s still has %d source_content rows", sharedHash, n)
 	}
 	if n := countRows(t, cache,
 		`SELECT COUNT(*) FROM source_metadata WHERE content_hash = ?`, string(sharedHash),
 	); n != 0 {
 		t.Errorf("evicted blob %s still has %d source_metadata references", sharedHash, n)
 	}
 	// The JSON metadata sidecars for both referencing paths must be
 	// removed along with the rows.
 	for _, path := range []string{"/a.jpg", "/b.jpg"} {
 		pathHash := HashPath(path + "?")
 		if cache.srcMetadata.Exists("src.example.com", pathHash) {
 			t.Errorf("metadata sidecar for %s must be removed with its row", path)
 		}
 	}
 	// The more recently used blob survives fully intact.
 	if !cache.srcContent.Exists(recentHash) {
 		t.Errorf("recently used blob %s must survive eviction", recentHash)
 	}
 	if n := countRows(t, cache,
 		`SELECT COUNT(*) FROM source_metadata WHERE content_hash = ?`, string(recentHash),
 	); n != 1 {
 		t.Errorf("recently used blob %s has %d source_metadata rows, want 1",
 			recentHash, n)
 	}
 	assertNoDanglingReferences(t, cache)
 }
 func TestEvictionKeepsEverythingWhenUnderLimit(t *testing.T) {
 	t.Parallel()
 	cache, _ := newEvictionTestCache(t, 1<<30)
 	content := bytes.Repeat([]byte{0xDF}, 800)
 	hash := storeEvictionTestSource(t, cache, "src.example.com", "/a.jpg", content)
 	h := storeEvictionTestSource(t, cache, "src.example.com", "/b.jpg", content)
 	if h != hash {
 		t.Fatalf("identical content produced different hashes: %s vs %s", h, hash)
 	}
 	storeEvictionTestVariant(t, cache, testVariantKeyOne,
 		bytes.Repeat([]byte{0xE0}, 500))
 	err := cache.EvictToLimit(context.Background())
 	if err != nil {
 		t.Fatalf("EvictToLimit failed: %v", err)
 	}
 	if !cache.srcContent.Exists(hash) {
 		t.Errorf("blob %s must not be evicted while usage is under the limit", hash)
 	}
 	if n := countRows(t, cache,
 		`SELECT COUNT(*) FROM source_metadata WHERE content_hash = ?`, string(hash),
 	); n != 2 {
 		t.Errorf("blob %s has %d source_metadata rows, want 2", hash, n)
 	}
 	if !cache.variants.Exists(testVariantKeyOne) {
 		t.Error("variant must not be evicted while usage is under the limit")
 	}
 	assertNoDanglingReferences(t, cache)
 }
 func TestZeroMaxBytesDisablesDiskCache(t *testing.T) {
 	t.Parallel()
 	cache, tmpDir := newEvictionTestCache(t, 0)
 	req := &ImageRequest{
 		SourceHost: "src.example.com",
 		SourcePath: "/a.jpg",
 		Format:     FormatJPEG,
 		Quality:    85,
 		FitMode:    FitCover,
 	}
 	assertDisabledCacheWritesAreNoOps(t, cache, req)
 	assertDisabledCacheReadsAlwaysMiss(t, cache, req)
 	assertDisabledCacheTracksNothing(t, cache)
 	assertDisabledCacheWroteNothingToDisk(t, tmpDir)
 }
 // assertDisabledCacheWritesAreNoOps verifies that stores against a
 // disabled cache report success without recording anything.
 func assertDisabledCacheWritesAreNoOps(
 	t *testing.T, cache *Cache, req *ImageRequest,
 ) {
 	t.Helper()
 	ctx := t.Context()
 	err := cache.StoreVariant(
 		ctx, CacheKey(req), bytes.NewReader([]byte("data")), "image/webp",
 	)
 	if err != nil {
 		t.Fatalf("StoreVariant on disabled cache must be a no-op, got error: %v", err)
 	}
 	result := &httpfetcher.FetchResult{
 		StatusCode:    200,
 		ContentType:   testContentTypeJPEG,
 		ContentLength: 4,
 		Headers:       map[string][]string{},
 	}
 	hash, err := cache.StoreSource(ctx, req, bytes.NewReader([]byte("data")), result)
 	if err != nil {
 		t.Fatalf("StoreSource on disabled cache must be a no-op, got error: %v", err)
 	}
 	if hash != "" {
 		t.Errorf("StoreSource on disabled cache returned hash %q, want empty", hash)
 	}
 }
 // assertDisabledCacheReadsAlwaysMiss verifies that lookups against a
 // disabled cache never report a hit.
 func assertDisabledCacheReadsAlwaysMiss(
 	t *testing.T, cache *Cache, req *ImageRequest,
 ) {
 	t.Helper()
 	ctx := t.Context()
 	lookup, err := cache.Lookup(ctx, req)
 	if err != nil {
 		t.Fatalf("Lookup on disabled cache failed: %v", err)
 	}
 	if lookup.Hit {
 		t.Error("Lookup on disabled cache must always miss")
 	}
 	srcHash, srcType, err := cache.LookupSource(ctx, req)
 	if err != nil {
 		t.Fatalf("LookupSource on disabled cache failed: %v", err)
 	}
 	if srcHash != "" || srcType != "" {
 		t.Errorf("LookupSource on disabled cache = (%q, %q), want empty",
 			srcHash, srcType)
 	}
 }
 // assertDisabledCacheTracksNothing verifies that a disabled cache
 // records no usage and writes no accounting rows.
 func assertDisabledCacheTracksNothing(t *testing.T, cache *Cache) {
 	t.Helper()
 	usage, err := cache.UsageBytes(t.Context())
 	if err != nil {
 		t.Fatalf("UsageBytes failed: %v", err)
 	}
 	if usage != 0 {
 		t.Errorf("UsageBytes on disabled cache = %d, want 0", usage)
 	}
 	if n := countRows(t, cache, `SELECT COUNT(*) FROM source_content`); n != 0 {
 		t.Errorf("disabled cache wrote %d source_content rows, want 0", n)
 	}
 	if n := countRows(t, cache, `SELECT COUNT(*) FROM source_metadata`); n != 0 {
 		t.Errorf("disabled cache wrote %d source_metadata rows, want 0", n)
 	}
 }
 // assertDisabledCacheWroteNothingToDisk verifies that a disabled cache
 // creates neither the cache directory tree nor any file under stateDir.
 func assertDisabledCacheWroteNothingToDisk(t *testing.T, stateDir string) {
 	t.Helper()
 	_, err := os.Stat(filepath.Join(stateDir, "cache"))
 	if !os.IsNotExist(err) {
 		t.Errorf("disabled cache must not create the cache directory tree "+
 			"(stat err=%v)", err)
 	}
 	var foundFiles []string
 	walkErr := filepath.WalkDir(stateDir,
 		func(path string, d fs.DirEntry, err error) error {
 			if err != nil {
 				return err
 			}
 			if !d.IsDir() {
 				foundFiles = append(foundFiles, path)
 			}
 			return nil
 		})
 	if walkErr != nil {
 		t.Fatalf("failed to walk state dir: %v", walkErr)
 	}
 	if len(foundFiles) != 0 {
 		t.Errorf("disabled cache wrote files to disk: %v", foundFiles)
 	}
 }
 func TestEvictionRunsUnderWritePressure(t *testing.T) {
 	t.Parallel()
 	const limit = 1500
 	cache, _ := newEvictionTestCache(t, limit)
 	// An interval far longer than the test ensures only write
 	// pressure can trigger eviction here.
 	cache.StartEviction(time.Hour)
 	defer cache.StopEviction()
 	keys := []VariantKey{
 		testVariantKeyOne, testVariantKeyTwo, testVariantKeyThree,
 	}
 	fills := []byte{0x11, 0x12, 0x13}
 	for i, key := range keys {
 		storeEvictionTestVariant(t, cache, key,
 			bytes.Repeat([]byte{fills[i]}, 1000))
 	}
 	usage := waitForUsageAtOrBelow(t, cache, limit, 5*time.Second)
 	if usage > limit {
 		t.Errorf("write pressure did not trigger eviction: usage = %d, want <= %d",
 			usage, limit)
 	}
 	assertNoDanglingReferences(t, cache)
 }
 func TestEvictionRunsOnPeriodicSchedule(t *testing.T) {
 	t.Parallel()
 	const limit = 1500
 	cache, _ := newEvictionTestCache(t, limit)
 	// Start the evictor while the cache is empty, then create tracked
 	// over-limit state WITHOUT going through the store methods, so no
 	// write-pressure notification fires and only the periodic ticker
 	// can trigger eviction.
 	cache.StartEviction(100 * time.Millisecond)
 	defer cache.StopEviction()
 	keys := []VariantKey{
 		testVariantKeyOne, testVariantKeyTwo, testVariantKeyThree,
 	}
 	fills := []byte{0x21, 0x22, 0x23}
 	for i, key := range keys {
 		content := bytes.Repeat([]byte{fills[i]}, 1000)
 		_, err := cache.variants.Store(key, bytes.NewReader(content), "image/webp")
 		if err != nil {
 			t.Fatalf("failed to store variant file: %v", err)
 		}
 		_, err = cache.db.ExecContext(t.Context(),
 			`INSERT INTO variant_content (cache_key, size_bytes, content_type)
 			 VALUES (?, ?, ?)`,
 			string(key), len(content), "image/webp",
 		)
 		if err != nil {
 			t.Fatalf("failed to insert variant accounting row: %v", err)
 		}
 	}
 	usage := waitForUsageAtOrBelow(t, cache, limit, 5*time.Second)
 	if usage > limit {
 		t.Errorf("periodic schedule did not trigger eviction: usage = %d, want <= %d",
 			usage, limit)
 	}
 	assertNoDanglingReferences(t, cache)
 }
 func TestStartEvictionReconcilesAccountingWithDisk(t *testing.T) {
 	t.Parallel()
 	cache, _ := newEvictionTestCache(t, 1<<30)
 	// An untracked variant file on disk (e.g. written before this
 	// feature existed) must be adopted into the accounting.
 	untracked := bytes.Repeat([]byte{0x31}, 1000)
 	_, err := cache.variants.Store(
 		testVariantKeyOne, bytes.NewReader(untracked), "image/webp",
 	)
 	if err != nil {
 		t.Fatalf("failed to store untracked variant file: %v", err)
 	}
 	// An accounting row whose file is missing must be dropped.
 	_, err = cache.db.ExecContext(t.Context(),
 		`INSERT INTO variant_content (cache_key, size_bytes, content_type)
 		 VALUES (?, ?, ?)`,
 		"deadbeef0001", 700, "image/webp",
 	)
 	if err != nil {
 		t.Fatalf("failed to insert stale variant accounting row: %v", err)
 	}
 	cache.StartEviction(time.Hour)
 	defer cache.StopEviction()
 	deadline := time.Now().Add(5 * time.Second)
 	var usage int64
 	for time.Now().Before(deadline) {
 		var err error
 		usage, err = cache.UsageBytes(context.Background())
 		if err != nil {
 			t.Fatalf("UsageBytes failed: %v", err)
 		}
 		if usage == 1000 {
 			break
 		}
 		time.Sleep(25 * time.Millisecond)
 	}
 	if usage != 1000 {
 		t.Errorf("usage after reconciliation = %d, want 1000 "+
 			"(untracked file adopted, stale row dropped)", usage)
 	}
 	if n := countRows(t, cache,
 		`SELECT COUNT(*) FROM variant_content WHERE cache_key = ?`,
 		string(testVariantKeyOne),
 	); n != 1 {
 		t.Errorf("untracked variant file was not adopted into accounting (rows=%d)", n)
 	}
 	if n := countRows(t, cache,
 		`SELECT COUNT(*) FROM variant_content WHERE cache_key = ?`, "deadbeef0001",
 	); n != 0 {
 		t.Errorf("stale accounting row without a file was not dropped (rows=%d)", n)
 	}
 }
 // TestPeriodicReconciliationAdoptsFileThatAppearsAfterStartup proves
 // reconciliation is not a one-shot startup-only pass: it must also run
 // on the periodic ticker, so a variant file that lands on disk with no
 // accounting row well after startup (e.g. because StoreVariant's
 // best-effort accounting insert failed under transient contention, or
 // any other cause of an untracked file appearing during steady-state
 // operation) is still adopted into accounting eventually, rather than
 // staying invisible to UsageBytes/EvictToLimit until the next process
 // restart.
 func TestPeriodicReconciliationAdoptsFileThatAppearsAfterStartup(t *testing.T) {
 	t.Parallel()
 	cache, _ := newEvictionTestCache(t, 1<<30)
 	const interval = 100 * time.Millisecond
 	cache.StartEviction(interval)
 	defer cache.StopEviction()
 	// Let startup reconciliation run and settle on an empty cache
 	// before introducing the untracked file, so the adoption we assert
 	// below can only be the work of a later, periodic pass.
 	time.Sleep(3 * interval)
 	// Simulate a variant whose accounting insert failed after the
 	// process was already running and serving requests: the content
 	// file is written directly, bypassing StoreVariant's (and thus its
 	// accounting insert) entirely, exactly as would happen if that
 	// insert had failed and only the file write had succeeded.
 	untracked := bytes.Repeat([]byte{0x41}, 900)
 	_, err := cache.variants.Store(
 		"aabbccdd0099", bytes.NewReader(untracked), "image/webp",
 	)
 	if err != nil {
 		t.Fatalf("failed to store untracked variant file: %v", err)
 	}
 	deadline := time.Now().Add(5 * time.Second)
 	var usage int64
 	for time.Now().Before(deadline) {
 		var err error
 		usage, err = cache.UsageBytes(context.Background())
 		if err != nil {
 			t.Fatalf("UsageBytes failed: %v", err)
 		}
 		if usage == 900 {
 			break
 		}
 		time.Sleep(25 * time.Millisecond)
 	}
 	if usage != 900 {
 		t.Errorf("usage after periodic reconciliation = %d, want 900 "+
 			"(a file that appeared after startup reconciliation already ran must still "+
 			"be adopted by a later periodic pass)", usage)
 	}
 	if n := countRows(t, cache,
 		`SELECT COUNT(*) FROM variant_content WHERE cache_key = ?`, "aabbccdd0099",
 	); n != 1 {
 		t.Errorf("file that appeared after startup was not adopted by periodic "+
 			"reconciliation (rows=%d)", n)
 	}
 }
 // TestEvictSourceBlobExcludesConcurrentStoreOfIdenticalContent exercises
 // the exact TOCTOU window between evictSourceBlob's row-deletion
 // transaction commit and its content file unlink: a concurrent
 // StoreSource for a different source path whose content hashes to the
 // same value (real SHA-256 dedup, not a contrived case) must not be
 // able to insert a fresh row referencing the file while eviction is
 // mid-unlink, and must not lose its own store once eviction has fully
 // released the content hash.
 func TestEvictSourceBlobExcludesConcurrentStoreOfIdenticalContent(t *testing.T) {
 	t.Parallel()
 	cache, _ := newEvictionTestCache(t, 1<<30)
 	ctx := context.Background()
 	content := bytes.Repeat([]byte{0x55}, 400)
 	hash := storeEvictionTestSource(t, cache,
 		"race.example.com", "/first.jpg", content)
 	proceed := make(chan struct{})
 	storeAttempted := make(chan struct{})
 	cache.evictSourceBlobTestHook = func(gotHash ContentHash) {
 		if gotHash != hash {
 			t.Errorf("test hook invoked for hash %s, want %s", gotHash, hash)
 		}
 		close(storeAttempted)
 		<-proceed
 	}
 	evictDone := make(chan error, 1)
 	go func() {
 		evictDone <- cache.evictSourceBlob(ctx, hash)
 	}()
 	// Wait until eviction has committed its delete transaction and is
 	// paused (inside the test hook) immediately before unlinking the
 	// content file: exactly the window the review flagged.
 	<-storeAttempted
 	storeDone := storeIdenticalContentConcurrently(ctx, cache, content)
 	// The concurrent store must not be able to complete while eviction
 	// still holds the content hash (i.e. before the file is unlinked):
 	// if it could, it would insert a row referencing a file about to be
 	// removed out from under it.
 	select {
 	case err := <-storeDone:
 		t.Fatalf("StoreSource for identical content completed (err=%v) while eviction "+
 			"still held the content hash open between commit and unlink; the store and "+
 			"the evict of identical content are not mutually exclusive", err)
 	case <-time.After(200 * time.Millisecond):
 		// Expected: the store is blocked behind eviction's exclusion.
 	}
 	close(proceed)
 	err := <-evictDone
 	if err != nil {
 		t.Fatalf("evictSourceBlob failed: %v", err)
 	}
 	err = <-storeDone
 	if err != nil {
 		t.Fatalf("StoreSource failed: %v", err)
 	}
 	assertNoDanglingReferences(t, cache)
 	dupHash, _, err := cache.LookupSource(ctx, &ImageRequest{
 		SourceHost: "race.example.com",
 		SourcePath: "/dup.jpg",
 	})
 	if err != nil {
 		t.Fatalf("LookupSource failed: %v", err)
 	}
 	if dupHash == "" {
 		t.Fatal("re-stored blob was lost: the store legitimately ran after eviction " +
 			"released the content hash and must have recreated the file and row")
 	}
 	if !cache.srcContent.Exists(dupHash) {
 		t.Errorf("source_content/source_metadata references %s but its file is missing",
 			dupHash)
 	}
 }
 // storeIdenticalContentConcurrently starts a StoreSource for a second
 // source path whose body hashes to the same content hash, returning the
 // channel its error is delivered on.
 func storeIdenticalContentConcurrently(
 	ctx context.Context, cache *Cache, content []byte,
 ) chan error {
 	storeDone := make(chan error, 1)
 	go func() {
 		req := &ImageRequest{
 			SourceHost: "race.example.com",
 			SourcePath: "/dup.jpg",
 			Format:     FormatJPEG,
 			Quality:    85,
 			FitMode:    FitCover,
 		}
 		result := &httpfetcher.FetchResult{
 			StatusCode:    200,
 			ContentType:   testContentTypeJPEG,
 			ContentLength: int64(len(content)),
 			Headers: map[string][]string{
 				testHeaderContentType: {testContentTypeJPEG},
 			},
 		}
 		_, err := cache.StoreSource(ctx, req, bytes.NewReader(content), result)
 		storeDone <- err
 	}()
 	return storeDone
 }
--- a/internal/imgcache/service.go
+++ b/internal/imgcache/service.go
@@ -315,7 +315,6 @@ func (s *Service) fetchAndProcess(
 		return nil, fmt.Errorf("upstream fetch failed: %w", err)
 	}
 	defer func() { _ = fetchResult.Content.Close() }()
 	// Read and validate the source content
@@ -425,7 +424,7 @@ func (s *Service) processAndStore(
 	// Store variant to cache
 	err = s.cache.StoreVariant(
-		ctx, cacheKey, bytes.NewReader(processedData), processResult.ContentType,
+		cacheKey, bytes.NewReader(processedData), processResult.ContentType,
 	)
 	if err != nil {
 		s.log.Warn("failed to store variant", "error", err)
--- a/internal/imgcache/storage.go
+++ b/internal/imgcache/storage.go
@@ -66,29 +66,55 @@ func (s *ContentStorage) Store(r io.Reader) (ContentHash, int64, error) {
 	hash := ContentHash(hex.EncodeToString(h[:]))
 	size := int64(len(data))
-	err = s.writeIfAbsent(hash, data)
+	// Build path: <basedir>/<ab>/<cd>/<hash>
-	if err != nil {
+	path := s.hashToPath(hash)
 		return "", 0, err
 	}
 	// Check if already exists
 	_, err = os.Stat(path)
 	if err == nil {
 		return hash, size, nil
 	}
-// StoreHashed writes pre-hashed content to storage at the path derived
+	// Create directory structure
-// from hash, without recomputing it. Callers that already know the
+	dir := filepath.Dir(path)
-// hash before writing (e.g. because they must hold a hash-keyed lock
+
-// across the whole store operation) use this instead of Store. Like
+	err = os.MkdirAll(dir, StorageDirPerm)
 // Store, it is idempotent: content already on disk at that path is
 // left untouched.
 func (s *ContentStorage) StoreHashed(
 	hash ContentHash, data []byte,
 ) (int64, error) {
 	err := s.writeIfAbsent(hash, data)
 	if err != nil {
-		return 0, err
+		return "", 0, fmt.Errorf("failed to create directory: %w", err)
 	}
-	return int64(len(data)), nil
+	// Write to temp file first, then rename for atomicity
 	tmpFile, err := os.CreateTemp(dir, ".tmp-*")
 	if err != nil {
 		return "", 0, fmt.Errorf("failed to create temp file: %w", err)
 	}
 	tmpPath := tmpFile.Name()
 	_, err = tmpFile.Write(data)
 	if err != nil {
 		_ = tmpFile.Close()
 		_ = os.Remove(tmpPath)
 		return "", 0, fmt.Errorf("failed to write content: %w", err)
 	}
 	err = tmpFile.Close()
 	if err != nil {
 		_ = os.Remove(tmpPath)
 		return "", 0, fmt.Errorf("failed to close temp file: %w", err)
 	}
 	// Atomic rename
 	err = os.Rename(filepath.Clean(tmpPath), filepath.Clean(path))
 	if err != nil {
 		_ = os.Remove(tmpPath)
 		return "", 0, fmt.Errorf("failed to rename temp file: %w", err)
 	}
 	return hash, size, nil
 }
 // Load returns a reader for the content with the given hash.
@@ -150,67 +176,6 @@ func (s *ContentStorage) Exists(hash ContentHash) bool {
 	return err == nil
 }
 // writeIfAbsent writes data to the path derived from hash, unless
 // content already exists there, via a temp-file-plus-rename so
 // concurrent readers never observe a partial file.
 func (s *ContentStorage) writeIfAbsent(hash ContentHash, data []byte) error {
 	// Build path: <basedir>/<ab>/<cd>/<hash>
 	path := s.hashToPath(hash)
 	// Check if already exists
 	_, statErr := os.Stat(path)
 	if statErr == nil {
 		return nil
 	}
 	// Create directory structure
 	dir := filepath.Dir(path)
 	err := os.MkdirAll(dir, StorageDirPerm)
 	if err != nil {
 		return fmt.Errorf("failed to create directory: %w", err)
 	}
 	// Write to temp file first, then rename for atomicity
 	tmpFile, err := os.CreateTemp(dir, ".tmp-*")
 	if err != nil {
 		return fmt.Errorf("failed to create temp file: %w", err)
 	}
 	tmpPath := tmpFile.Name()
 	// Each failure path below unlinks the temp file explicitly. This
 	// replaces a deferred cleanup that read a named result, which the
 	// canonical config does not permit; the set of paths that remove
 	// tmpPath, and the order relative to Close, is unchanged. This
 	// mirrors how MetadataStorage.Store and VariantStorage.Store below
 	// already express the same cleanup.
 	_, err = tmpFile.Write(data)
 	if err != nil {
 		_ = tmpFile.Close()
 		_ = os.Remove(tmpPath)
 		return fmt.Errorf("failed to write content: %w", err)
 	}
 	err = tmpFile.Close()
 	if err != nil {
 		_ = os.Remove(tmpPath)
 		return fmt.Errorf("failed to close temp file: %w", err)
 	}
 	// Atomic rename
 	err = os.Rename(filepath.Clean(tmpPath), filepath.Clean(path))
 	if err != nil {
 		_ = os.Remove(tmpPath)
 		return fmt.Errorf("failed to rename temp file: %w", err)
 	}
 	return nil
 }
 // hashToPath converts a hash to a file path: <basedir>/<ab>/<cd>/<hash>
 func (s *ContentStorage) hashToPath(hash ContentHash) string {
 	h := string(hash)
@@ -557,24 +522,6 @@ func (s *VariantStorage) Delete(key VariantKey) error {
 	return nil
 }
 // DeleteWithMeta removes the content at the given key together with
 // its .meta sidecar file. A missing file is not an error.
 func (s *VariantStorage) DeleteWithMeta(key VariantKey) error {
 	err := s.Delete(key)
 	if err != nil {
 		return err
 	}
 	metaPath := s.keyToPath(key) + ".meta"
 	err = os.Remove(metaPath)
 	if err != nil && !os.IsNotExist(err) {
 		return fmt.Errorf("failed to delete variant metadata: %w", err)
 	}
 	return nil
 }
 // keyToPath converts a key to a file path: <basedir>/<ab>/<cd>/<key>
 func (s *VariantStorage) keyToPath(key VariantKey) string {
 	k := string(key)
--- a/internal/imgcache/testutil_internal_test.go
+++ b/internal/imgcache/testutil_internal_test.go
@@ -24,7 +24,6 @@ const (
 	testHostExample     = "example.com"
 	testPathCat         = "/photos/cat.jpg"
 	testContentTypeJPEG = "image/jpeg"
 	testHeaderContentType = "Content-Type"
 )
 // TestFixtures contains paths to test files in the mock filesystem.
--- a/internal/signature/golden_test.go
+++ b/internal/signature/golden_test.go
@@ -111,7 +111,7 @@ func TestSigner_GoldenVectors(t *testing.T) {
 			gotPath, _, _ := signer.GenerateSignedURL(&urlReq, time.Hour)
 			if gotPath != tt.wantSignedPath {
-				t.Errorf("GenerateSignedURL() path = %q, want %q (signed URL layout changed?)",
+				t.Errorf("GenerateSignedURL() path = %q, want %q (layout changed?)",
 					gotPath, tt.wantSignedPath)
 			}
 		})
--- a/script/test
+++ b/script/test
@@ -17,7 +17,7 @@ run_with_cgo_deps() {
 main() {
    cd "$ROOT"
    echo "Running tests..."
-    run_with_cgo_deps "CGO_ENABLED=1 go test -timeout 30s -race -v ./..."
+    run_with_cgo_deps "CGO_ENABLED=1 go test -timeout 30s -v ./..."
 }
 main "$@"