stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity
Files
8d78dd219b5e44c835e511491a4750f4a3ee3640
git.stella-ops.org/docs/modules/concelier/operations/cache.md
StellaOps Bot 8d78dd219b
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
feat(advisory-ai): Add deployment guide, Dockerfile, and Helm chart for on-prem packaging 
- Introduced a comprehensive deployment guide for AdvisoryAI, detailing local builds, remote inference toggles, and scaling guidance.
- Created a multi-role Dockerfile for building WebService and Worker images.
- Added a docker-compose file for local and offline deployment.
- Implemented a Helm chart for Kubernetes deployment with persistence and remote inference options.
- Established a new API endpoint `/advisories/summary` for deterministic summaries of observations and linksets.
- Introduced a JSON schema for risk profiles and a validator to ensure compliance with the schema.
- Added unit tests for the risk profile validator to ensure functionality and error handling.
2025-11-23 00:35:33 +02:00

2.9 KiB
Raw Blame History

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.

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.

TODOs / follow-ups

  • Add integration test that exercises a cache hit path and validates transparency headers.
  • Document cache configuration knobs in appsettings.* once finalized.
  • Add summary cache integration test once /advisories/summary endpoint is implemented.