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), 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

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)

6.6 KiB Raw Blame History