git.stella-ops.org/src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GroundTruth.Abstractions/AGENTS.md

GroundTruth.Abstractions - Agent Instructions

Module Overview

This library defines the core abstractions for ground-truth symbol source connectors following the Concelier/Excititor Aggregation-Only Contract (AOC) pattern.

Key Interfaces

• ISymbolSourceConnector - Main connector interface with three-phase pipeline (Fetch → Parse → Map)
• ISymbolSourceConnectorPlugin - Plugin registration interface
• ISymbolObservationWriteGuard - AOC enforcement for immutable observations
• ISymbolObservationRepository - Persistence for observations
• ISecurityPairService - Pre/post CVE binary pair management

AOC Invariants (MUST follow)

1. No derived scores at ingest - Never add confidence, accuracy, or match_score during ingestion
2. Immutable observations - Once created, observations are never modified
3. Supersession chain - New versions use SupersedesId to link to previous
4. Mandatory provenance - All observations must have source_id, document_uri, fetched_at, content_hash
5. Deterministic hashing - Use canonical JSON with sorted keys, UTC timestamps, hex-lowercase hashes

Adding New Connectors

1. Implement ISymbolSourceConnector (or extend SymbolSourceConnectorBase)
2. Implement ISymbolSourceConnectorPlugin for DI registration
3. Add source definition to SymbolSourceDefinitions
4. Follow the three-phase pattern:
   • Fetch: Download raw data, store with digest, update cursor
   • Parse: Validate, extract symbols, create DTOs
   • Map: Build canonical observations, enforce AOC, persist

Testing Requirements

• Unit tests for all public interfaces
• AOC write guard tests for all violation codes
• Deterministic hash tests with frozen fixtures
• Offline-compatible test fixtures

Dependencies

• Microsoft.Extensions.Logging.Abstractions
• Microsoft.Extensions.Options
• System.Text.Json