sprints work.

src/BinaryIndex/__Libraries/StellaOps.BinaryIndex.GroundTruth.Abstractions/AGENTS.md

@@ -0,0 +1,44 @@
+# 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