# 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