40 lines
3.5 KiB
Markdown
40 lines
3.5 KiB
Markdown
# Provenance Cache (Provcache) with VeriKey Composite Hash
|
|
|
|
## Module
|
|
__Libraries
|
|
|
|
## Status
|
|
VERIFIED
|
|
|
|
## Description
|
|
Provenance Cache (Provcache) backend with VeriKey composite hash (source + SBOM + VEX + policy + signer + time window), DecisionDigest canonicalized evaluation output, Valkey read-through with Postgres write-behind, and Policy Engine integration for cache-accelerated decisions.
|
|
|
|
## Implementation Details
|
|
- **VeriKeyBuilder**: `src/__Libraries/StellaOps.Provcache/VeriKeyBuilder.cs` -- fluent builder for composite provenance identity key: `VeriKey = SHA256(source_hash || sbom_hash || vex_hash_set_hash || merge_policy_hash || signer_set_hash || time_window)`; multi-partial: `.Source.cs`, `.Sbom.cs`, `.Vex.cs`, `.Policy.cs`, `.Signer.cs`, `.TimeWindow.cs`, `.Hashing.cs`, `.Build.cs`; each component ensures cache invalidation when relevant inputs change
|
|
- **DecisionDigestBuilder**: `src/__Libraries/StellaOps.Provcache/DecisionDigestBuilder.cs` -- builder for canonicalized evaluation output digest; multi-partial: `.VeriKey.cs`, `.Verdict.cs`, `.Proof.cs`, `.ReplaySeed.cs`, `.Timestamps.cs`, `.TrustScore.cs`, `.Hashing.cs`, `.Build.cs`; uses `ProvcacheOptions` and `TimeProvider` for deterministic computation
|
|
- **ProvcacheService**: `src/__Libraries/StellaOps.Provcache/ProvcacheService.cs` -- multi-partial service: `.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)
|
|
- **WriteBehindQueue**: `src/__Libraries/StellaOps.Provcache/WriteBehindQueue.cs` -- multi-partial: `.Enqueue.cs`, `.Drain.cs`, `.Batch.cs`, `.Run.cs`, `.Metrics.cs`; `WriteBehindQueueHostedService` for background processing
|
|
- **ValkeyProvcacheStore**: `src/__Libraries/StellaOps.Provcache.Valkey/ValkeyProvcacheStore.cs` -- Valkey-backed cache: `.Get.cs`, `.GetMany.cs`, `.GetOrSet.cs`, `.Set.cs`, `.SetMany.cs`, `.Invalidate.cs`, `.InvalidateByPattern.cs`
|
|
- **PostgresProvcacheRepository**: `src/__Libraries/StellaOps.Provcache.Postgres/PostgresProvcacheRepository.cs` -- write-behind persistence: `.Read.cs`, `.Upsert.cs`, `.Delete.cs`, `.DeleteFeedExpired.cs`, `.DeletePolicySigner.cs`, `.Revocations.cs`, `.Metrics.cs`, `.Mapping.cs`
|
|
- **ProvcacheOptions**: `src/__Libraries/StellaOps.Provcache/ProvcacheOptions.cs` -- multi-partial: `.Cache.cs`, `.Chunking.cs`, `.TimeWindow.cs`, `.Ttl.cs`, `.WriteBehind.cs`
|
|
- **ProvcacheTelemetry**: `src/__Libraries/StellaOps.Provcache/ProvcacheTelemetry.cs` -- OpenTelemetry metrics: `.Counters.cs`, `.Gauges.cs`, `.Histograms.cs`, `.Metrics.Hits.cs`, `.Metrics.Invalidation.cs`, `.Metrics.Latency.cs`
|
|
- **Source**: SPRINT_8200_0001_0001_provcache_core_backend.md
|
|
|
|
## E2E Test Plan
|
|
- [ ] Verify VeriKey computation is deterministic for same inputs (source, SBOM, VEX, policy, signer, time window)
|
|
- [ ] Test VeriKey changes when any component hash changes (cache invalidation)
|
|
- [ ] Verify DecisionDigest captures canonicalized evaluation output
|
|
- [ ] Test read-through pattern: cache miss triggers computation and stores result
|
|
- [ ] Verify Valkey store handles get/set/invalidate operations correctly
|
|
- [ ] Test write-behind queue batches writes to Postgres
|
|
- [ ] Verify time window bucketing enables controlled cache expiry
|
|
- [ ] Test ProvcacheService.Prune removes expired entries
|
|
|
|
|
|
## Verification
|
|
|
|
- **Verified**: 2026-02-13T20:30:00Z
|
|
- **Run**: run-001
|
|
- **Tier**: Tier 2d (Library/Internal)
|
|
- **Verdict**: PASS
|