Concelier Advisory Chunk Cache

Status: draft · aligned with LNM v1 (frozen 2025-11-17)

Audience: Stella Ops operators and integrators working with the Concelier advisory APIs.

The advisory chunk cache speeds up repeated reads of advisory chunks and summaries while keeping every response deterministic and provenance-auditable. This page documents the cache key model, the transparency headers Concelier returns, and the safety guarantees that make the cache air-gap friendly.

Purpose

• Reduce repeated /advisories/{key}/chunks rebuilds while preserving determinism and provenance integrity.
• Give consoles and debugging tools transparent cache provenance (key material and TTL) so evidence chains stay 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.

Summary cache (for /advisories/summary)

• Optional, disabled by default; enables deterministic paging for graph/console overlays.
• Key material (pipe-delimited, normalized/sorted where applicable):
  • tenant
  • purls[] (sorted)
  • aliases[] (sorted, lower-case)
  • sources[] (sorted, lower-case)
  • confidence_gte
  • conflicts_only
  • sort
  • take
  • afterCursor (opaque; includes last sort tuple)
• Transparency headers (if enabled): X-Stella-Cache-Key (sha256-16), X-Stella-Cache-Hit, X-Stella-Cache-Ttl.
• Ordering for cacheable results: sort (advisory|observedAt), then advisoryKey, then linksetId; cursor encodes the tuple to keep pagination stable when new linksets land.

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.

Open follow-ups

• Add an integration test that exercises a cache-hit path and validates the transparency headers.
• Document the cache configuration knobs in appsettings.* once they are finalised.
• Add a summary-cache integration test once the /advisories/summary endpoint ships.