stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
cf5b72974f923126944f4dcd47e85864ebb31a3b
git.stella-ops.org/docs/features/unchecked/libraries/provenance-cache-with-verikey-composite-hash.md

3.4 KiB
Raw Blame History

Provenance Cache (Provcache) with VeriKey Composite Hash

Module

__Libraries

Status

IMPLEMENTED

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