# Advisory Lens Architecture

> **Status: Production (Shared Library).** AdvisoryLens is a standalone deterministic library at `src/__Libraries/StellaOps.AdvisoryLens/`, **not** merged into AdvisoryAI. The two modules serve different purposes: AdvisoryLens provides pattern-based case matching without AI inference; AdvisoryAI provides LLM-powered advisory analysis with guardrails. They can be composed together but are architecturally independent. The library is currently available for integration but not yet referenced from any WebService `Program.cs`.

## 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/StellaOps.AdvisoryLens/`
- Tests: `src/__Libraries/__Tests/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

```csharp
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