Refactor code structure for improved readability and maintainability; removed redundant code blocks and optimized function calls.

docs/modules/concelier/operations/cache.md

@@ -0,0 +1,40 @@
+# Concelier Advisory Chunk Cache
+
+Status: draft · aligned with LNM v1 (frozen 2025-11-17)
+
+## Purpose
+- Reduce repeated `/advisories/{key}/chunks` rebuilds while preserving determinism and provenance integrity.
+- Provide consoles and debugging tools with transparent cache provenance (key material and TTL) to keep evidence chains auditable.
+
+## Cache key (deterministic)
+- Inputs (pipe-delimited, all lower-case where applicable):
+  - `tenant`
+  - `advisoryKey`
+  - `chunkLimit`
+  - `observationLimit`
+  - `minimumLength`
+  - `sectionFilter` (sorted, case-insensitive)
+  - `formatFilter` (sorted, case-insensitive)
+  - advisory fingerprint (hash of canonical advisory)
+  - ordered observations: each `observationId@contentHash@createdAtTicks@format`
+- Implementation: `AdvisoryChunkCacheKey.Create` (WebService). Normalized ordering ensures replayability across nodes.
+- External disclosure: headers expose a hashed cache key (see below) rather than the full raw key.
+
+## Response transparency headers
+- `X-Stella-Cache-Key`: SHA-256 hex of the cache key (default 16 chars) for tamper-evident correlation.
+- `X-Stella-Cache-Hit`: `1` on hit, `0` on miss.
+- `X-Stella-Cache-Ttl`: configured TTL in seconds (0 when caching disabled).
+- Consumers may log these headers; do **not** treat them as stable API contract for filtering.
+
+## Determinism & safety
+- No PII in keys or headers; key inputs are tenant/advisory identifiers already present in requests.
+- Timestamps use UTC ticks; content hashes retain upstream digest prefix (e.g., `sha256:`) to distinguish sources.
+- Cache TTL defaults to 0 (disabled) unless configured; safe for offline/air-gapped deployments.
+
+## Testing notes
+- Unit coverage: `AdvisoryChunkCacheKeyTests` (ordering, filter casing) and `AdvisoryChunkBuilderTests` (observationPath pointers influence chunk IDs).
+- Integration tests should assert headers when cache is enabled; disable cache for tests that assert body-only determinism.
+
+## TODOs / follow-ups
+- Add integration test that exercises a cache hit path and validates transparency headers.
+- Document cache configuration knobs in `appsettings.*` once finalized.