# Provcache: Signer-Aware Invalidation, Evidence Chunk Paging, and Air-Gap Export

## Module
__Libraries (Provcache)

## Status
IMPLEMENTED

## Description
Large multi-wave feature: evidence chunk storage (with SHA-256 per-chunk verification and ChunkManifest for lazy fetching), paged evidence API (GetChunkRangeAsync), minimal proof bundle export (lite/standard/strict density), signer-aware cache invalidation (InvalidationType.SignerSetHash), feed epoch invalidation (InvalidationType.FeedEpochOlderThan), lazy evidence fetch (HTTP + sneakernet), revocation ledger with replay service, and CLI commands (stella prov export/import). Most waves DONE, but messaging bus subscription tasks and CLI e2e tests are BLOCKED pending service integration.

## What's Implemented
- **ProvcacheService**: `src/__Libraries/StellaOps.Provcache/ProvcacheService.cs` -- multi-partial: `.Get.cs` (lookup by VeriKey), `.GetOrCompute.cs` (read-through pattern), `.Set.cs` (store with TTL), `.Invalidate.cs`/`.InvalidateBy.cs` (targeted invalidation), `.Prune.cs` (expired entry cleanup), `.Metrics.cs` (telemetry), `.Tracking.cs` (usage tracking)
- **InvalidationRequest**: `src/__Libraries/StellaOps.Provcache/InvalidationRequest.cs` -- record with `Type` (InvalidationType), `Value`, `Reason`, `Actor`; factory methods: `ByPolicyHash(hash)`, `BySignerSetHash(hash)`, `ByFeedEpochOlderThan(epoch)`, `ByPattern(pattern)`
- **InvalidationType**: `src/__Libraries/StellaOps.Provcache/InvalidationType.cs` -- enum: `PolicyHash`, `SignerSetHash`, `FeedEpochOlderThan`, `Pattern`, `Expired`
- **InvalidationResult**: `src/__Libraries/StellaOps.Provcache/InvalidationResult.cs` -- result of invalidation operation
- **EvidenceChunk**: `src/__Libraries/StellaOps.Provcache/EvidenceChunk.cs` -- record: `ChunkId` (Guid), `ProofRoot` (string), `ChunkIndex` (int, zero-based), `ChunkHash` (SHA-256), `Blob` (byte[]), `BlobSize` (int), `ContentType` (MIME), `CreatedAt`
- **ChunkManifest**: `src/__Libraries/StellaOps.Provcache/ChunkManifest.cs` -- record: `ProofRoot`, `TotalChunks`, `TotalSize` (long bytes), `Chunks` (IReadOnlyList<ChunkMetadata>), `GeneratedAt`; used for lazy fetching where blobs are retrieved on demand
- **ChunkMetadata**: `src/__Libraries/StellaOps.Provcache/ChunkMetadata.cs` -- metadata-only chunk descriptor
- **IEvidenceChunkRepository**: `src/__Libraries/StellaOps.Provcache/IEvidenceChunkRepository.cs` -- interface: `GetChunksAsync(proofRoot)`, `GetChunkAsync(proofRoot, chunkIndex)`, `GetChunkRangeAsync(proofRoot, startIndex, count)` (paged retrieval), `GetManifestAsync(proofRoot)`, `StoreChunksAsync(proofRoot, chunks)`, `DeleteChunksAsync(proofRoot)`, `GetChunkCountAsync`, `GetTotalSizeAsync`
- **ValkeyProvcacheStore**: `src/__Libraries/StellaOps.Provcache.Valkey/ValkeyProvcacheStore.cs` -- multi-partial: `.Get.cs`, `.GetMany.cs`, `.GetOrSet.cs`, `.Set.cs`, `.SetMany.cs`, `.Invalidate.cs`, `.InvalidateByPattern.cs`
- **PostgresProvcacheRepository**: `src/__Libraries/StellaOps.Provcache.Postgres/PostgresProvcacheRepository.cs` -- multi-partial: `.Read.cs`, `.Upsert.cs`, `.Delete.cs`, `.DeleteFeedExpired.cs`, `.DeletePolicySigner.cs`, `.Revocations.cs`, `.Metrics.cs`, `.Mapping.cs`
- **PostgresEvidenceChunkRepository**: `src/__Libraries/StellaOps.Provcache.Postgres/PostgresEvidenceChunkRepository.cs` -- multi-partial: `.Get.cs`, `.Manifest.cs`, `.Mapping.cs`, `.Metrics.cs`, `.Range.cs`, `.Store.cs`
- **RevocationLedger**: `src/__Libraries/StellaOps.Provcache/Revocation/` -- `IRevocationLedger` (RecordAsync, GetEntriesSinceAsync, GetEntriesByTypeAsync, GetLatestSeqNoAsync, GetRevocationsForKeyAsync, GetStatsAsync), `InMemoryRevocationLedger` (multi-partial: `.Query.cs`, `.Stats.cs`), `RevocationEntry` (SeqNo, RevocationId, RevocationType, RevokedKey, Reason, EntriesInvalidated, Source, CorrelationId, RevokedAt, Metadata)
- **RevocationReplayService**: `src/__Libraries/StellaOps.Provcache/Revocation/RevocationReplayService.cs` -- multi-partial: `.Apply.cs`, `.Checkpoint.cs`, `.Process.cs`, `.Replay.cs`, `.Result.cs`, `.State.cs`
- **WriteBehindQueue**: `src/__Libraries/StellaOps.Provcache/WriteBehindQueue.cs` -- multi-partial: `.Enqueue.cs`, `.Drain.cs`, `.Batch.cs`, `.Run.cs`, `.Metrics.cs`
- **Attestation Models**: `src/__Libraries/StellaOps.Provcache/` -- `ProvcacheOciAttestationRequest.cs`, `ProvcacheOciAttestationResult.cs`, `ProvcachePredicate.cs`, `ProvcacheStatement.cs`, `ProvcacheSubject.cs` for OCI attestation integration
- **Telemetry**: `src/__Libraries/StellaOps.Provcache/ProvcacheTelemetry.cs` -- multi-partial covering activities, counters, gauges, histograms, and metrics
- **Provenance Attestation Core**: `src/Provenance/StellaOps.Provenance.Attestation/` -- full attestation library with build models, promotion attestation, signers, and verification pipeline

## What's Missing
- **SignerRevokedEvent handler**: No event handler listening for signer revocation events and invalidating cached provenance records signed by the revoked key. The signer infrastructure and `InvalidationType.SignerSetHash` exist but the messaging bus fan-out is not wired.
- **FeedEpochAdvancedEvent handler**: No event handler listening for feed epoch advancement and invalidating stale provenance cache entries referencing the previous epoch's advisory data.
- **Cross-module event bus integration**: The event-driven fan-out requires integration with the broader event bus (likely via the Scheduler or Orchestrator) which is not yet connected.
- **CLI e2e tests**: No e2e test coverage for `stella prov export/import` commands (BLOCKED pending CLI integration).
- **Air-gap export bundle with DSSE signing**: Partial -- sneakernet transport bundle needs DSSE signing for integrity verification before import.

## Implementation Plan
- Integrate messaging bus subscriptions for `SignerRevokedEvent` triggering `InvalidationRequest.BySignerSetHash()`
- Integrate messaging bus subscriptions for `FeedEpochAdvancedEvent` triggering `InvalidationRequest.ByFeedEpochOlderThan()`
- Complete air-gap export bundle with DSSE signing for offline transport
- Implement CLI e2e test coverage for provenance export/import commands
- Verify revocation replay service correctly re-applies invalidation events after restore

## Related Documentation
- Source: SPRINT_8200_0001_0002_provcache_invalidation_airgap.md
- Provenance attestation library: `src/Provenance/StellaOps.Provenance.Attestation/`
- Signer module: `src/Signer/`
- Attestor proof chain (Merkle infrastructure): `src/Attestor/__Libraries/StellaOps.Attestor.ProofChain/Merkle/`

## Merged From
- `libraries/provcache-invalidation-and-evidence-chunk-paging.md` (deleted)
- `provenance/provcache-invalidation-with-signerrevokedevent-and-feedepochadvancedevent-fan-ou.md` (deleted)