save progress

2025-12-26 22:03:32 +02:00
parent 9a4cd2e0f7
commit e6c47c8f50
3634 changed files with 253222 additions and 56632 deletions
--- a/docs/modules/aoc/architecture.md
+++ b/docs/modules/aoc/architecture.md
@@ -0,0 +1,126 @@
+# component_architecture_aoc.md - **Stella Ops AOC** (2025Q4)
+
+> Append-Only Contract enforcement via Roslyn analyzers.
+
+> **Scope.** Library architecture for **AOC** (Append-Only Contracts): Roslyn-based code analyzers that enforce data integrity rules during vulnerability ingestion.
+
+---
+
+## 0) Mission & boundaries
+
+**Mission.** Enforce **append-only contract rules** during data ingestion. Prevent connectors from writing to fields that should only be computed by downstream merge/decisioning pipelines (severity, CVSS, effective status, risk scores).
+
+**Boundaries.**
+
+* AOC provides **compile-time enforcement** via Roslyn analyzers.
+* AOC analyzers run on **ingestion code** (Connectors, Ingestion assemblies).
+* AOC **does not** run on merge/decisioning code (those are allowed to write derived fields).
+
+---
+
+## 1) Solution & project layout
+
+```
+src/Aoc/
+ ├─ __Analyzers/
+ │   └─ StellaOps.Aoc.Analyzers/           # Roslyn DiagnosticAnalyzers
+ │       ├─ AocForbiddenFieldAnalyzer.cs   # Main analyzer
+ │       └─ ...
+ │
+ ├─ __Libraries/
+ │   ├─ StellaOps.Aoc/                     # Core abstractions (IAocGuard, etc.)
+ │   └─ StellaOps.Aoc.AspNetCore/          # ASP.NET Core integration
+ │
+ ├─ StellaOps.Aoc.Cli/                     # CLI for manual validation
+ │
+ └─ __Tests/
+     ├─ StellaOps.Aoc.Analyzers.Tests/
+     ├─ StellaOps.Aoc.AspNetCore.Tests/
+     └─ StellaOps.Aoc.Tests/
+```
+
+---
+
+## 2) Core concept
+
+### 2.1 Forbidden Fields
+
+During ingestion, the following fields are **forbidden** (computed by decisioning pipeline):
+
+| Field | Reason |
+|-------|--------|
+| `severity` | Computed from CVSS + context |
+| `cvss` | Normalized from multiple sources |
+| `cvss_vector` | Parsed/validated post-merge |
+| `effective_status` | VEX consensus outcome |
+| `effective_range` | Merged affected ranges |
+| `merged_from` | Provenance tracking |
+| `consensus_provider` | VEX provider selection |
+| `reachability` | Runtime analysis result |
+| `asset_criticality` | Policy engine computation |
+| `risk_score` | Final risk calculation |
+
+### 2.2 Derived Fields
+
+Any field prefixed with `effective_` is treated as derived and forbidden in ingestion context.
+
+---
+
+## 3) Diagnostic Rules
+
+| ID | Severity | Description |
+|----|----------|-------------|
+| `AOC0001` | Error | Forbidden field write detected |
+| `AOC0002` | Error | Derived field (effective_*) write detected |
+| `AOC0003` | Warning | Unguarded database write without IAocGuard validation |
+
+---
+
+## 4) Usage
+
+### 4.1 Analyzer Reference
+
+Add analyzer reference to connector projects:
+
+```xml
+<ItemGroup>
+  <PackageReference Include="StellaOps.Aoc.Analyzers" PrivateAssets="all" />
+</ItemGroup>
+```
+
+### 4.2 Guard Usage
+
+Wrap database writes with AOC guard:
+
+```csharp
+public class MyConnector
+{
+    private readonly IAocGuard _aocGuard;
+
+    public async Task IngestAsync(Advisory advisory, CancellationToken ct)
+    {
+        // Guard validates no forbidden fields are written
+        await _aocGuard.ValidateAsync(advisory, ct);
+        await _repository.InsertAsync(advisory, ct);
+    }
+}
+```
+
+---
+
+## 5) Configuration
+
+AOC analyzers activate based on assembly/namespace patterns:
+
+- `*.Connector.*` assemblies
+- `*.Ingestion` assemblies
+- `*.Connector` assemblies
+- Namespaces containing `.Connector.` or `.Ingestion`
+
+---
+
+## Related Documentation
+
+* Concelier: `../concelier/architecture.md` (uses AOC for connectors)
+* Excititor: `../excititor/architecture.md` (uses AOC for VEX ingestion)
+* Determinism: `../../telemetry/` (AOC ensures deterministic merge inputs)