git.stella-ops.org/docs-archived/modules/advisory-lens/architecture.md

Advisory Lens Architecture

Status: Archived (2026-03-04). AdvisoryLens is preserved under src/__Libraries/_archived/StellaOps.AdvisoryLens/ with tests at src/__Libraries/_archived/StellaOps.AdvisoryLens.Tests/. It was archived in Sprint 217 after consumer verification confirmed zero production usage.

Purpose

StellaOps.AdvisoryLens is a deterministic, offline-first library for semantic case matching of vulnerability advisories. It produces ranked suggestions and contextual hints without AI/LLM inference.

Scope

• Working directory: src/__Libraries/_archived/StellaOps.AdvisoryLens/
• Tests: src/__Libraries/_archived/StellaOps.AdvisoryLens.Tests/
• Integration entry point: services.AddAdvisoryLens(...)

Models

Type	Purpose
AdvisoryCase	Advisory input including CVE, PURL, severity, and metadata
LensContext	Evaluation envelope (advisory case, tenant id, evidence refs, optional timestamp)
CasePattern	Matching rule with severity/ecosystem/CVE conditions and default suggestion payload
LensSuggestion	Ranked operator-facing recommendation with confidence and action
LensHint	Contextual evidence hint grouped by deterministic categories
LensResult	Evaluation output containing suggestions, hints, matched pattern ids, timestamp, and input hash

Matching Algorithm

1. CaseMatcher evaluates each CasePattern against the input AdvisoryCase
2. Scoring factors are severity range match, PURL ecosystem match, and CVE pattern match
3. Disqualifying mismatches (severity out of range, wrong ecosystem) return score 0.0
4. If no factors are configured for a pattern, score defaults to 0.5
5. Positive-score matches are sorted by score descending, then PatternId ascending for deterministic tie-breaking
6. AdvisoryLensService maps sorted matches into suggestions with rank = position + 1

Hint Generation

Hints are derived from LensContext and sorted by category ordinal then text:

• Severity: High or Critical advisories emit a priority remediation hint
• Reachability: non-empty reachability evidence emits code-path guidance
• VEX: non-empty VEX references emit a count-based hint
• Policy: non-empty policy traces emit a count-based hint

Integration

services.AddAdvisoryLens(patterns, timeProvider);

• Registers IAdvisoryLensService as a singleton
• Uses empty patterns when none are provided
• Uses TimeProvider.System when no provider is injected

Determinism Guarantees

• Stable ordering for matches and hints
• Input hash computed as sha256: + SHA-256 over canonical JSON (camelCase, no indentation, nulls ignored)
• Timestamp comes from LensContext.EvaluationTimestampUtc or injected TimeProvider
• Identical inputs and clock source produce identical LensResult

Offline Posture

• No network dependencies in library behavior
• In-process, side-effect-free evaluation and scoring
• Tests validate execution with no HTTP or external service setup