# 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)