partly or unimplemented features - now implemented

docs/modules/advisory-lens/architecture.md

@@ -0,0 +1,63 @@
+# Advisory Lens Architecture
+
+## 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