docs consolidation

2025-12-25 12:16:13 +02:00
parent deb82b4f03
commit 223843f1d1
34 changed files with 2141 additions and 106 deletions
--- a/docs/modules/provcache/README.md
+++ b/docs/modules/provcache/README.md
@@ -1,6 +1,6 @@
 # Provcache Module

-> **Status: Planned** — This module is documented for upcoming implementation in Sprint 8200. The design is finalized but source code does not yet exist.
+> **Status: Implemented** — Core library shipped in Sprint 8200.0001.0001. API endpoints, caching, invalidation and write-behind queue are operational. Policy Engine integration pending architectural review.

 > Provenance Cache — Maximizing Trust Evidence Density

@@ -54,11 +54,17 @@ A composite hash that uniquely identifies a provenance decision context:

 ```
 VeriKey = SHA256(
+    "v1|"              ||  // Version prefix for compatibility
    source_hash        ||  // Image/artifact digest
+    "|"                ||
    sbom_hash          ||  // Canonical SBOM hash
+    "|"                ||
    vex_hash_set_hash  ||  // Sorted VEX statement hashes
+    "|"                ||
    merge_policy_hash  ||  // PolicyBundle hash
+    "|"                ||
    signer_set_hash    ||  // Signer certificate hashes
+    "|"                ||
    time_window            // Epoch bucket
 )
 ```
@@ -74,6 +80,31 @@ VeriKey = SHA256(
 | `signer_set_hash` | Key rotation → new key (security) |
 | `time_window` | Temporal bucketing → controlled expiry |

+#### VeriKey Composition Rules
+
+1. **Hash Normalization**: All input hashes are normalized to lowercase with `sha256:` prefix stripped if present
+2. **Set Hash Computation**: For VEX statements and signer certificates:
+   - Individual hashes are sorted lexicographically (ordinal)
+   - Sorted hashes are concatenated with `|` delimiter
+   - Result is SHA256-hashed
+   - Empty sets use well-known sentinels (`"empty-vex-set"`, `"empty-signer-set"`)
+3. **Time Window Computation**: `floor(timestamp.Ticks / bucket.Ticks) * bucket.Ticks` in UTC ISO-8601 format
+4. **Output Format**: `sha256:<64-char-lowercase-hex>`
+
+#### Code Example
+
+```csharp
+var veriKey = new VeriKeyBuilder(options)
+    .WithSourceHash("sha256:abc123...")           // Image digest
+    .WithSbomHash("sha256:def456...")             // SBOM digest
+    .WithVexStatementHashes(["sha256:v1", "sha256:v2"])  // Sorted automatically
+    .WithMergePolicyHash("sha256:policy...")      // Policy bundle
+    .WithCertificateHashes(["sha256:cert1"])      // Signer certs
+    .WithTimeWindow(DateTimeOffset.UtcNow)        // Auto-bucketed
+    .Build();
+// Returns: "sha256:789abc..."
+```
+
 ### DecisionDigest

 Canonicalized representation of an evaluation result:
@@ -231,6 +262,56 @@ stella prov import --input proof-lite.json --lazy-fetch --backend https://api.st

 ## Configuration

+### C# Configuration Class
+
+The `ProvcacheOptions` class (section name: `"Provcache"`) exposes the following settings:
+
+| Property | Type | Default | Validation | Description |
+|----------|------|---------|------------|-------------|
+| `DefaultTtl` | `TimeSpan` | 24h | 1min–7d | Default time-to-live for cache entries |
+| `MaxTtl` | `TimeSpan` | 7d | 1min–30d | Maximum allowed TTL regardless of request |
+| `TimeWindowBucket` | `TimeSpan` | 1h | 1min–24h | Time window bucket for VeriKey computation |
+| `ValkeyKeyPrefix` | `string` | `"stellaops:prov:"` | — | Key prefix for Valkey storage |
+| `EnableWriteBehind` | `bool` | `true` | — | Enable async Postgres persistence |
+| `WriteBehindFlushInterval` | `TimeSpan` | 5s | 1s–5min | Interval for flushing write-behind queue |
+| `WriteBehindMaxBatchSize` | `int` | 100 | 1–10000 | Maximum batch size per flush |
+| `WriteBehindQueueCapacity` | `int` | 10000 | 100–1M | Max queue capacity (blocks when full) |
+| `WriteBehindMaxRetries` | `int` | 3 | 0–10 | Retry attempts for failed writes |
+| `ChunkSize` | `int` | 65536 | 1KB–1MB | Evidence chunk size in bytes |
+| `MaxChunksPerEntry` | `int` | 1000 | 1–100000 | Max chunks per cache entry |
+| `AllowCacheBypass` | `bool` | `true` | — | Allow clients to force re-evaluation |
+| `DigestVersion` | `string` | `"v1"` | — | Serialization version for digests |
+| `HashAlgorithm` | `string` | `"SHA256"` | — | Hash algorithm for VeriKey/digest |
+| `EnableValkeyCache` | `bool` | `true` | — | Enable Valkey layer (false = Postgres only) |
+| `SlidingExpiration` | `bool` | `false` | — | Refresh TTL on cache hits |
+
+### appsettings.json Example
+
+```json
+{
+  "Provcache": {
+    "DefaultTtl": "24:00:00",
+    "MaxTtl": "7.00:00:00",
+    "TimeWindowBucket": "01:00:00",
+    "ValkeyKeyPrefix": "stellaops:prov:",
+    "EnableWriteBehind": true,
+    "WriteBehindFlushInterval": "00:00:05",
+    "WriteBehindMaxBatchSize": 100,
+    "WriteBehindQueueCapacity": 10000,
+    "WriteBehindMaxRetries": 3,
+    "ChunkSize": 65536,
+    "MaxChunksPerEntry": 1000,
+    "AllowCacheBypass": true,
+    "DigestVersion": "v1",
+    "HashAlgorithm": "SHA256",
+    "EnableValkeyCache": true,
+    "SlidingExpiration": false
+  }
+}
+```
+
+### YAML Example (Helm/Kubernetes)
+
 ```yaml
 provcache:
  # TTL configuration
@@ -253,6 +334,21 @@ provcache:
  digestVersion: "v1"
 ```

+### Dependency Injection Registration
+
+```csharp
+// In Program.cs or Startup.cs
+services.AddProvcache(configuration);
+
+// Or with explicit configuration
+services.AddProvcache(options =>
+{
+    options.DefaultTtl = TimeSpan.FromHours(12);
+    options.EnableWriteBehind = true;
+    options.WriteBehindMaxBatchSize = 200;
+});
+```
+
 ## Observability

 ### Metrics
@@ -367,6 +463,35 @@ CREATE TABLE provcache.prov_revocations (
 );
 ```

+## Implementation Status
+
+### Completed (Sprint 8200.0001.0001)
+
+| Component | Path | Status |
+|-----------|------|--------|
+| Core Models | `src/__Libraries/StellaOps.Provcache/Models/` | ✅ Done |
+| VeriKeyBuilder | `src/__Libraries/StellaOps.Provcache/VeriKeyBuilder.cs` | ✅ Done |
+| DecisionDigest | `src/__Libraries/StellaOps.Provcache/DecisionDigest.cs` | ✅ Done |
+| Caching Layer | `src/__Libraries/StellaOps.Provcache/Caching/` | ✅ Done |
+| WriteBehindQueue | `src/__Libraries/StellaOps.Provcache/Persistence/` | ✅ Done |
+| API Endpoints | `src/__Libraries/StellaOps.Provcache.Api/` | ✅ Done |
+| Unit Tests (53) | `src/__Libraries/__Tests/StellaOps.Provcache.Tests/` | ✅ Done |
+
+### Blocked
+
+| Component | Reason |
+|-----------|--------|
+| Policy Engine Integration | `PolicyEvaluator` is `internal sealed`; requires architectural review to expose injection points for `IProvcacheService` |
+
+### Pending
+
+| Component | Sprint |
+|-----------|--------|
+| Signer Revocation Events | 8200.0001.0002 |
+| CLI Export/Import | 8200.0001.0002 |
+| UI Badges & Proof Tree | 8200.0001.0003 |
+| Grafana Dashboards | 8200.0001.0003 |
+
 ## Implementation Sprints

 | Sprint | Focus | Key Deliverables |