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.

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.

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.

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.

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.

Add integration test that exercises a cache hit path and validates transparency headers.
Document cache configuration knobs in appsettings.* once finalized.