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:

<ItemGroup>
  <PackageReference Include="StellaOps.Aoc.Analyzers" PrivateAssets="all" />
</ItemGroup>

4.2 Guard Usage

Wrap database writes with AOC guard:

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

Concelier: ../concelier/architecture.md (uses AOC for connectors)
Excititor: ../excititor/architecture.md (uses AOC for VEX ingestion)
Determinism: ../../telemetry/ (AOC ensures deterministic merge inputs)

3.5 KiB Raw Blame History