fix(ccr): honor workspace dir for sqlite store (#1564)

## Description

CCR's default SQLite backend ignores `HEADROOM_WORKSPACE_DIR`. When
users relocate Headroom's read-write state with the canonical workspace
env var, the CCR store still wrote `ccr_store.db` under `~/.headroom`
unless they also set `HEADROOM_CCR_SQLITE_PATH`.

This change keeps `HEADROOM_CCR_SQLITE_PATH` as the strongest per-store
override, then resolves the default SQLite database as `workspace_dir()
/ "ccr_store.db"` from `headroom.paths.workspace_dir()`. With no env
vars set, `workspace_dir()` still falls back to `~/.headroom`, so the
effective default remains unchanged. The default backend stays SQLite,
preserving restart survival and multi-worker sharing. Closes #1558

## Type of Change

- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- Route `headroom.cache.backends.sqlite.default_db_path()` through
`headroom.paths.workspace_dir()` when `HEADROOM_CCR_SQLITE_PATH` is
unset.
- Preserve `HEADROOM_CCR_SQLITE_PATH` as the strongest override.
- Keep the no-env effective fallback at `~/.headroom/ccr_store.db`
through `workspace_dir()` resolution.
- Update default-path wording in SQLite/compression-store/backends docs
to remove unconditional fallback claims.
- Add focused regression and preservation tests in
`tests/test_ccr_sqlite_backend.py` for:
- workspace override when `HEADROOM_WORKSPACE_DIR` is set and
`HEADROOM_CCR_SQLITE_PATH` is unset.
  - env path override still winning.
  - no-env fallback to `~/.headroom`.
  - explicit `SQLiteBackend(db_path=...)` authority.
  - existing restart and two-connection behavior.

## Testing

- [x] Unit tests pass (`uv run pytest tests/test_ccr_sqlite_backend.py
-k "workspace_dir or sqlite_path_env_wins or home_fallback or
explicit_db_path or default_backend_is_sqlite or survives_reopen or
two_connections_share_data" -v`)
- [x] Linting passes (`uv run ruff check
headroom/cache/backends/sqlite.py headroom/cache/compression_store.py
headroom/cache/backends/__init__.py tests/test_ccr_sqlite_backend.py`)
- [ ] Type checking not run (`uv run mypy headroom`)
- [x] New tests added for new functionality when applicable
- [x] Manual testing performed

### Test Output

```text
Base proof before the production fix:
uv run pytest tests/test_ccr_sqlite_backend.py -k "workspace_dir" -v
FAILED tests/test_ccr_sqlite_backend.py::TestDefaults::test_workspace_dir - AssertionError:
assert 'C:\Users\Rod\AppData\Local\Temp\pytest-of-Rod\pytest-484\test_workspace_dir0\fake_home\.headroom\ccr_store.db' == 'C:\Users\Rod\AppData\Local\Temp\pytest-of-Rod\pytest-484\test_workspace_dir0\workspace\ccr_store.db'
1 failed, 20 deselected

Focused validation after the fix:
uv run pytest tests/test_ccr_sqlite_backend.py -k "workspace_dir or sqlite_path_env_wins or home_fallback or explicit_db_path or default_backend_is_sqlite or survives_reopen or two_connections_share_data" -v
7 passed, 14 deselected, 1 warning in 0.20s
uv run ruff check headroom/cache/backends/sqlite.py headroom/cache/compression_store.py headroom/cache/backends/__init__.py tests/test_ccr_sqlite_backend.py
All checks passed!
```

## Real Behavior Proof

- Environment: local pytest filesystem-path regression tests with
temporary home and workspace directories.
- Exact command / steps: run `uv run pytest
tests/test_ccr_sqlite_backend.py -k "workspace_dir" -v` on base with the
new regression test present, then run `uv run pytest
tests/test_ccr_sqlite_backend.py -k "workspace_dir or
sqlite_path_env_wins or home_fallback or explicit_db_path or
default_backend_is_sqlite or survives_reopen or
two_connections_share_data" -v` and `uv run ruff check
headroom/cache/backends/sqlite.py headroom/cache/compression_store.py
headroom/cache/backends/__init__.py tests/test_ccr_sqlite_backend.py` on
the patched branch.
- Observed result: the base proof fails because the default backend path
resolves to `fake_home\\.headroom\\ccr_store.db` instead of
`workspace\\ccr_store.db`; after the fix, the focused pytest selection
passes, `HEADROOM_CCR_SQLITE_PATH` still wins, the no-env fallback still
resolves through `~/.headroom`, explicit `db_path` remains
authoritative, and `ruff check` passes.
- Not tested: live proxy traffic with real CCR compression/retrieve
requests, because the changed surface is the deterministic default path
resolver and default backend construction.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I have updated the CHANGELOG.md if applicable

## Additional Notes

`CHANGELOG.md` should remain unchanged because the repo's release
automation derives changelog entries from conventional commits.

headroom/cache/backends/__init__.py

@@ -13,7 +13,7 @@ Usage:
     from headroom.cache.backends import SQLiteBackend, CompressionStoreBackend
     from headroom.cache.compression_store import CompressionStore, get_compression_store
 
-    # Env-driven default (SQLite at ~/.headroom/ccr_store.db)
+    # Env-driven default (SQLite at workspace_dir()/ccr_store.db)
     store = get_compression_store()
 
     # Direct construction defaults to in-memory; pass a backend for persistence

headroom/cache/backends/sqlite.py

@@ -13,7 +13,7 @@ cannot provide, both load-bearing for the no-accuracy-loss guarantee:
 
 Set ``HEADROOM_CCR_BACKEND=memory`` to opt back into the in-memory
 backend, or ``HEADROOM_CCR_SQLITE_PATH`` to relocate the database file
-(default ``~/.headroom/ccr_store.db``).
+(default ``workspace_dir()/ccr_store.db``).
 """
 
 from __future__ import annotations
@@ -49,11 +49,13 @@ _PURGE_INTERVAL = 60.0
 
 
 def default_db_path() -> Path:
-    """Resolve the database path (env override or ~/.headroom/)."""
+    """Resolve the database path (env override, else workspace root)."""
     env = os.environ.get("HEADROOM_CCR_SQLITE_PATH", "").strip()
     if env:
         return Path(env).expanduser()
-    return Path.home() / ".headroom" / "ccr_store.db"
+    from ...paths import workspace_dir
+
+    return workspace_dir() / "ccr_store.db"
 
 
 class SQLiteBackend:

headroom/cache/compression_store.py

@@ -946,9 +946,9 @@ def clear_request_compression_store() -> None:
 def _create_default_ccr_backend() -> CompressionStoreBackend | None:
     """Create a CCR backend from env (e.g. HEADROOM_CCR_BACKEND=redis).
 
-    Default (env unset or "sqlite"): SQLiteBackend at
-    ~/.headroom/ccr_store.db — restart-safe and shared across worker
-    processes, which the session-scale 30-minute TTL assumes.
+    Default (env unset or "sqlite"): SQLiteBackend at workspace_dir()/ccr_store.db
+    — restart-safe and shared across worker processes, which the
+    session-scale 30-minute TTL assumes.
     "memory" opts back into the in-process dict. Other values load
     adapters via setuptools entry point 'headroom.ccr_backend'.
     Returns None to use InMemoryBackend.

tests/test_ccr_sqlite_backend.py

@@ -212,6 +212,56 @@ class TestDefaults:
         assert backend is not None
         assert backend.get_stats()["backend_type"] == "sqlite"
 
+    def test_workspace_dir(self, monkeypatch, tmp_path):
+        from headroom.cache.compression_store import _create_default_ccr_backend
+
+        workspace = tmp_path / "workspace"
+        fake_home = tmp_path / "fake_home"
+
+        monkeypatch.delenv("HEADROOM_CCR_BACKEND", raising=False)
+        monkeypatch.delenv("HEADROOM_CCR_SQLITE_PATH", raising=False)
+        monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(workspace))
+        monkeypatch.setenv("HOME", str(fake_home))
+        monkeypatch.setenv("USERPROFILE", str(fake_home))
+
+        backend = _create_default_ccr_backend()
+        assert backend is not None
+        assert str(backend._path) == str(workspace / "ccr_store.db")
+
+    def test_sqlite_path_env_wins(self, monkeypatch, tmp_path):
+        from headroom.cache.compression_store import _create_default_ccr_backend
+
+        workspace = tmp_path / "workspace"
+        sqlite_path = tmp_path / "sqlite_override.db"
+
+        monkeypatch.delenv("HEADROOM_CCR_BACKEND", raising=False)
+        monkeypatch.setenv("HEADROOM_WORKSPACE_DIR", str(workspace))
+        monkeypatch.setenv("HEADROOM_CCR_SQLITE_PATH", str(sqlite_path))
+        backend = _create_default_ccr_backend()
+
+        assert backend is not None
+        assert str(backend._path) == str(sqlite_path)
+
+    def test_home_fallback(self, monkeypatch, tmp_path):
+        from headroom.cache.compression_store import _create_default_ccr_backend
+
+        fake_home = tmp_path / "fake_home"
+
+        monkeypatch.delenv("HEADROOM_CCR_BACKEND", raising=False)
+        monkeypatch.delenv("HEADROOM_CCR_SQLITE_PATH", raising=False)
+        monkeypatch.delenv("HEADROOM_WORKSPACE_DIR", raising=False)
+        monkeypatch.setenv("HOME", str(fake_home))
+        monkeypatch.setenv("USERPROFILE", str(fake_home))
+
+        backend = _create_default_ccr_backend()
+        assert backend is not None
+        assert str(backend._path) == str(fake_home / ".headroom" / "ccr_store.db")
+
+    def test_explicit_db_path(self, tmp_path):
+        explicit = tmp_path / "explicit.db"
+        backend = SQLiteBackend(explicit)
+        assert backend._path == explicit
+
     def test_memory_opt_out(self, monkeypatch):
         from headroom.cache.compression_store import _create_default_ccr_backend