8d78dd219b
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- 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.
57 lines
2.9 KiB
Markdown
57 lines
2.9 KiB
Markdown
# 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.
|