wip: doctor/cli/docs/api to vector db consolidation; api hardening for descriptions, tenant, and scopes; migrations and conversions of all DALs to EF v10

src/__Libraries/StellaOps.Verdict/AGENTS.md

@@ -1,4 +1,4 @@
-# AGENTS.md — StellaOps.Verdict Module
+# AGENTS.md -- StellaOps.Verdict Module
 
 ## Overview
 
@@ -8,30 +8,67 @@ The StellaOps.Verdict module provides a **unified StellaVerdict artifact** that
 
 ```
 src/__Libraries/StellaOps.Verdict/
-├── Schema/
-│   └── StellaVerdict.cs          # Core verdict schema and supporting types
-├── Contexts/
-│   └── verdict-1.0.jsonld        # JSON-LD context for standards interop
-├── Services/
-│   ├── VerdictAssemblyService.cs # Assembles verdicts from components
-│   ├── VerdictSigningService.cs  # DSSE signing integration
-│   └── IVerdictAssemblyService.cs
-├── Persistence/
-│   ├── PostgresVerdictStore.cs   # PostgreSQL storage implementation
-│   ├── IVerdictStore.cs          # Storage interface
-│   ├── VerdictRow.cs             # EF Core entity
-│   └── Migrations/
-│       └── 001_create_verdicts.sql
-├── Api/
-│   ├── VerdictEndpoints.cs       # REST API endpoints
-│   └── VerdictContracts.cs       # Request/response DTOs
-├── Oci/
-│   └── OciAttestationPublisher.cs # OCI registry attestation
-├── Export/
-│   └── VerdictBundleExporter.cs  # Replay bundle export
-└── StellaOps.Verdict.csproj
++-- Schema/
+|   +-- StellaVerdict.cs          # Core verdict schema and supporting types
++-- Contexts/
+|   +-- verdict-1.0.jsonld        # JSON-LD context for standards interop
++-- Services/
+|   +-- VerdictAssemblyService.cs # Assembles verdicts from components
+|   +-- VerdictSigningService.cs  # DSSE signing integration
+|   +-- IVerdictAssemblyService.cs
++-- Persistence/
+|   +-- PostgresVerdictStore.cs   # PostgreSQL (EF Core) storage implementation
+|   +-- IVerdictStore.cs          # Storage interface
+|   +-- VerdictRow.cs             # EF Core entity (Fluent API mappings)
+|   +-- EfCore/
+|   |   +-- Context/
+|   |   |   +-- VerdictDbContext.cs                   # Partial DbContext with Fluent API
+|   |   |   +-- VerdictDesignTimeDbContextFactory.cs  # For dotnet ef CLI
+|   |   +-- CompiledModels/
+|   |       +-- VerdictDbContextModel.cs              # Compiled model singleton
+|   |       +-- VerdictDbContextModelBuilder.cs       # Compiled model builder
+|   |       +-- VerdictDbContextAssemblyAttributes.cs # Excluded from compilation
+|   +-- Postgres/
+|   |   +-- VerdictDataSource.cs       # DataSourceBase derivation, connection pool
+|   |   +-- VerdictDbContextFactory.cs # Runtime factory with compiled model hookup
+|   +-- Migrations/
+|       +-- 001_create_verdicts.sql
++-- Api/
+|   +-- VerdictEndpoints.cs       # REST API endpoints
+|   +-- VerdictContracts.cs       # Request/response DTOs
+|   +-- VerdictPolicies.cs        # Authorization policies
++-- Oci/
+|   +-- OciAttestationPublisher.cs # OCI registry attestation
++-- Export/
+|   +-- VerdictBundleExporter.cs  # Replay bundle export
++-- StellaOps.Verdict.csproj
 ```
 
+## DAL Architecture (EF Core v10)
+
+The Verdict persistence layer follows the EF Core v10 standards documented in `docs/db/EF_CORE_MODEL_GENERATION_STANDARDS.md`:
+
+- **DbContext**: `VerdictDbContext` (partial class, schema-injectable, Fluent API mappings)
+- **Schema**: `stellaops` (shared platform schema)
+- **Design-time factory**: `VerdictDesignTimeDbContextFactory` (for `dotnet ef` CLI)
+- **Runtime factory**: `VerdictDbContextFactory` (compiled model for default schema, reflection for non-default)
+- **DataSource**: `VerdictDataSource` extends `DataSourceBase` for connection pooling and tenant context
+- **Compiled model**: Stub in `EfCore/CompiledModels/`; assembly attributes excluded from compilation
+- **Migration registry**: Registered as `VerdictMigrationModulePlugin` in Platform.Database
+
+### Connection Pattern
+```csharp
+await using var connection = await _dataSource.OpenConnectionAsync(tenantId.ToString(), "reader", ct);
+await using var context = VerdictDbContextFactory.Create(connection, CommandTimeoutSeconds, GetSchemaName());
+// Use context.Verdicts with AsNoTracking() for reads...
+```
+
+### Schema Governance
+- SQL migrations in `Persistence/Migrations/` are the authoritative schema definition
+- EF Core models are derived from schema, not the reverse
+- No EF Core auto-migrations at runtime
+- Schema changes require new SQL migration files
+
 ## Key Concepts
 
 ### StellaVerdict Schema
@@ -115,6 +152,7 @@ var result = await publisher.PublishAsync(verdict, "registry.io/app:latest@sha25
 - `StellaOps.Attestor.Envelope`: DSSE signing
 - `StellaOps.Cryptography`: BLAKE3/SHA256 hashing
 - `StellaOps.Replay.Core`: Bundle structures
+- `StellaOps.Infrastructure.Postgres`: DataSourceBase, PostgresOptions, connection pooling
 
 ## Testing
 
@@ -126,7 +164,7 @@ Unit tests should cover:
 - Query filtering and pagination
 
 Integration tests should cover:
-- Full assembly → sign → store → query → verify flow
+- Full assembly -> sign -> store -> query -> verify flow
 - OCI publish/fetch cycle
 - Replay bundle export and verification
 
@@ -135,10 +173,14 @@ Integration tests should cover:
 1. **Determinism**: All JSON output must be deterministic (sorted keys, stable ordering)
 2. **Content Addressing**: VerdictId must match `ComputeVerdictId()` output
 3. **Immutability**: Use records with `init` properties
-4. **Tenant Isolation**: All store operations must include tenantId
+4. **Tenant Isolation**: All store operations must include tenantId; RLS enforced at DB level
 5. **Offline Support**: OCI publisher and CLI must handle offline mode
+6. **EF Core Standards**: Follow `docs/db/EF_CORE_MODEL_GENERATION_STANDARDS.md`
+7. **AsNoTracking**: Always use for read-only queries
+8. **DbContext per operation**: Create via VerdictDbContextFactory, not cached
 
 ## Related Sprints
 
 - SPRINT_1227_0014_0001: StellaVerdict Unified Artifact Consolidation
 - SPRINT_1227_0014_0002: Verdict UI Components (pending)
+- SPRINT_20260222_080: Verdict Persistence DAL to EF Core (queue order 16)