AOC (Aggregation-Only Contract)

WITHDRAWN (2026-09-27, SPRINT_20260927_003 PCD-62). The AOC libraries (StellaOps.Aoc, StellaOps.Aoc.AspNetCore), the StellaOps.Aoc.Analyzers Roslyn analyzer and the CLI Aoc plug-in are no longer built or shipped. Their sources are frozen under src/__Obsoleted/Aoc/ and src/__Obsoleted/Cli/ (CODE_OF_CONDUCT 15.4). No service referenced them, and the plug-in’s direct-PostgreSQL verify form (--postgres option) read an aoc_documents table that no migration creates. This page describes the withdrawn code and is kept for reference. Still live and separate: the aoc:verify scope. The core CLI aoc command was withdrawn on 2026-10-01 (SPRINT_20260928_008 PCD-153); the Platform /api/v1/aoc/* compatibility endpoints (Development and testing only) and the Console AOC pages were withdrawn on 2026-10-08 (SPRINT_20261007_002 CCP-005 and CCP-004).

Verified against commit 942a18727c (2026-09-26). Re-verify with: find src/Aoc -name '*.csproj' && grep -rl --include=*.csproj 'StellaOps.Aoc' src | grep -v -e '^src/Aoc/' -e '^src/__Obsoleted/'

Kind: shared libraries + Roslyn analyzer. No host, no service, no database, no compose or release-bundle entry. Source: src/Aoc/ (solution src/Aoc/StellaOps.Aoc.sln; also listed in src/StellaOps.sln)

Purpose

Audience: developers writing code that persists raw upstream data (advisories, VEX, other ingested documents), and reviewers checking that raw data is never enriched with computed fields at write time.

AOC enforces the aggregation-only rule: an ingestion path may persist raw upstream data with its provenance, but must not write fields that downstream merge/decisioning computes. Enforcement has two layers: a runtime write-guard library and a Roslyn analyzer. Some source comments and the CLI plugin manifest say “Append-Only Contract”; the canonical term is Aggregation-Only Contract.

Current consumers

The ingestion services that used the guard at runtime (Concelier and Excititor) were retired on 2026-08-04 and their sources now live under src/__Obsoleted/Concelier/. Production advisory and VEX ingestion is the vulnerability hub (../vulnerabilities/architecture.md), which does not reference the AOC libraries.

At this commit the only live project referencing StellaOps.Aoc is the CLI plugin src/Cli/__Libraries/StellaOps.Cli.Plugins.Aoc/, and it does not call the guard (see architecture §7-§8). No live project references StellaOps.Aoc.AspNetCore or StellaOps.Aoc.Analyzers. The libraries are maintained and tested, but no deployable currently enforces them.

Components

Libraries (src/Aoc/__Libraries/):

• StellaOps.Aoc — runtime guard IAocGuard / AocWriteGuard (Validate(JsonElement document, AocGuardOptions? options = null) returns AocGuardResult), ValidateOrThrow(...) extension raising AocGuardException, violation codes ERR_AOC_001..010 (AocViolationCode + ToErrorCode()), DI via AddAocGuard() (singleton IAocGuard).
• StellaOps.Aoc.AspNetCore — minimal-API endpoint filter (RequireAocGuard<TRequest>(...), two payload-selector overloads) and RFC 7807 problem responses (AocHttpResults.Problem).

Analyzer (src/Aoc/__Analyzers/):

• StellaOps.Aoc.Analyzers — one analyzer, AocForbiddenFieldAnalyzer, with diagnostics AOC0001 (forbidden field, Error), AOC0002 (derived effective_* field, Error), AOC0003 (unguarded database write, Warning). It fires only in ingestion contexts (assembly/namespace names containing .Connector/.Ingestion, [AocIngestion]/[AocIngestionContext] markers, or the MSBuild opt-ins StellaOpsAocIngestion, StellaOpsAocIngestionAssemblies, StellaOpsAocIngestionNamespacePrefixes); .Tests/.Analyzers assemblies are excluded. The analyzer’s forbidden set also names effective_status and effective_range explicitly.

Tests (src/Aoc/__Tests/): StellaOps.Aoc.Tests, StellaOps.Aoc.AspNetCore.Tests, StellaOps.Aoc.Analyzers.Tests.

CLI: no project in src/Aoc/, and no aoc command in src/Cli/: both former aoc verify implementations are withdrawn (see architecture §8).

Key concepts

Forbidden top-level fields (ERR_AOC_001): severity, cvss, cvss_vector, merged_from, consensus_provider, reachability, asset_criticality, risk_score.

Derived fields (ERR_AOC_006): any top-level field prefixed effective_.

Document shape: default required top-level fields are tenant, source, upstream, content, linkset. Codes: ERR_AOC_004 (missing provenance: upstream.content_hash, upstream.signature, content.raw), ERR_AOC_005 (signature payload missing), ERR_AOC_007 (unknown top-level field), ERR_AOC_008 (missing required field), ERR_AOC_009 (invalid tenant), ERR_AOC_010 (invalid signature metadata). ERR_AOC_002 (MergeAttempt) and ERR_AOC_003 (IdempotencyViolation) are reserved enum members that AocWriteGuard.Validate does not emit.

Options (AocGuardOptions, an immutable record): RequireTenant (default true), RequireSignatureMetadata (default true), AllowedSignatureFormats (empty = any), RequiredTopLevelFields, AllowedTopLevelFields. The ASP.NET Core filter uses an explicit guardOptions argument, else IOptions<AocGuardOptions>, else AocGuardOptions.Default.

HTTP mapping (AocHttpResults.Problem): RFC 7807, type https://stella-ops.org/problems/aoc-violation; status by the first sorted violation code — ERR_AOC_003 409, ERR_AOC_004/ERR_AOC_005 422, ERR_AOC_006 403, others 400.

Authority scope: aoc:verify (StellaOpsScopes.AocVerify).

Related documentation

• Architecture: ./architecture.md
• Guides: ./guides/aoc-guardrails.md, ./guides/guard-library.md
• Security invariants: ../../security/aoc-invariants.md
• CLI command guide: ../cli/guides/commands/aoc.md
• Historical consumers (retired): ../concelier/, ../excititor/