# GoldenSet Library Charter

## Mission
Provide foundational data models, storage, and validation for Golden Set definitions - ground-truth facts about vulnerability code-level manifestation.

## Responsibilities
- **Domain Models**: GoldenSetDefinition, VulnerableTarget, BasicBlockEdge, WitnessInput, GoldenSetMetadata
- **Validation**: Schema validation, CVE existence check, edge format validation, sink registry lookup
- **Storage**: PostgreSQL persistence with content-addressed retrieval
- **Serialization**: YAML round-trip serialization with snake_case convention
- **Sink Registry**: Lookup service for known sinks mapped to CWE categories

## Key Principles
1. **Immutability**: All models are immutable records with ImmutableArray collections
2. **Content-Addressing**: All golden sets have SHA256-based content digests for deduplication
3. **Determinism**: Serialization and hashing produce deterministic outputs
4. **Air-Gap Ready**: Validation supports offline mode without external lookups
5. **Human-Readable**: YAML as primary format for git-friendliness

## DAL Technology
- **Primary**: EF Core v10 DbContext (`EfCore/Context/GoldenSetDbContext.cs`) with 3 entities (definitions, targets, audit_log) in `golden_sets` schema.
- **Compiled model**: `EfCore/CompiledModels/GoldenSetDbContextModel` generated for runtime performance.
- **Legacy**: `PostgresGoldenSetStore` still uses NpgsqlDataSource directly (deferred from EF Core conversion). Mixed DAL acceptable per cutover strategy.
- **SQL migrations remain authoritative**: EF models are scaffolded FROM the SQL schema, never the reverse.

## Dependencies
- `BinaryIndex.Contracts` - Shared contracts and DTOs
- `Npgsql` - PostgreSQL driver
- `Npgsql.EntityFrameworkCore.PostgreSQL` - EF Core Npgsql provider
- `Microsoft.EntityFrameworkCore` - EF Core v10
- `YamlDotNet` - YAML serialization
- `Microsoft.Extensions.*` - DI, Options, Logging, Caching

## Required Reading
- `docs/modules/binary-index/golden-set-schema.md`
- `docs-archived/implplan/SPRINT_20260110_012_001_BINDEX_golden_set_foundation.md`
- `docs/db/EF_CORE_MODEL_GENERATION_STANDARDS.md`

## Test Strategy
- Unit tests in `StellaOps.BinaryIndex.GoldenSet.Tests`
- Integration tests with Testcontainers PostgreSQL
- Property-based tests for serialization round-trip