# Belnap K4 Trust Lattice Engine (VEX Resolution, Trust Algebra)

## Module
Policy

## Status
VERIFIED

## Description
Full K4 lattice implementation with 4-valued logic (unknown/true/false/conflict), trust labels, lattice store, claim score merging, conflict penalization, and disposition selection. VEX normalization for OpenVEX and CSAF formats. Deterministic, commutative, idempotent merge operations. Comprehensive tests including property-based tests.

## Implementation Details
- **K4Lattice**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/K4Lattice.cs` -- Belnap four-valued logic implementation
  - `K4Value` enum: Unknown (bottom), True, False, Conflict (top)
  - Knowledge ordering: Unknown < True|False < Conflict; True and False are incomparable
  - `Join(a, b)` -- knowledge join (union of support): T join F = Conflict; short-circuits on Conflict
  - `JoinAll(values)` -- order-independent aggregation over sequence; short-circuits on Conflict
  - `Meet(a, b)` -- knowledge meet (intersection): T meet F = Unknown; Conflict meet X = X
  - `LessOrEqual(a, b)` -- knowledge ordering predicate
  - `Negate(v)` -- swaps True/False; Unknown and Conflict are self-negating
  - `FromSupport(hasTrueSupport, hasFalseSupport)` -- constructs K4 value from support flags
  - Helper predicates: `HasTrueSupport`, `HasFalseSupport`, `IsDefinite`, `IsIndeterminate`
- **TrustLatticeEngine**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/TrustLatticeEngine.cs` -- orchestrates complete trust evaluation pipeline
  - Pipeline: VEX normalization -> claim ingestion -> K4 lattice evaluation -> disposition selection -> proof bundle generation
  - `IngestVex(document, format, principal, trustLabel?)` -- ingests VEX document via registered normalizers
  - `IngestClaim(claim)` / `IngestClaims(claims)` -- direct claim ingestion into LatticeStore
  - `GetDisposition(subject)` -- evaluates subject and returns DispositionResult
  - `MergeClaims(scoredClaims, policy?)` -- merges scored VEX claims using ClaimScore-based algorithm
  - `Evaluate(options?)` -- evaluates all subjects with optional proof bundle generation and subject filtering
  - Fluent `ClaimBuilder` with `Assert(atom, value)`, `Present()`, `Applies()`, `Reachable()`, `Mitigated()`, `Fixed()`, `Misattributed()` 
- **ClaimScoreMerger**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/ClaimScoreMerger.cs` -- lattice-based merge with conflict penalization
  - `Merge(scoredClaims, policy)` -- orders by adjusted score, specificity, original score; selects winner
  - `ConflictPenalizer` applies configurable penalty (default 0.25) to conflicting claims
  - `MergePolicy` options: `ConflictPenalty`, `PreferSpecificity`, `RequireReplayProofOnConflict`
  - Returns `MergeResult` with: winning claim, all scored claims, conflict records, confidence, RequiresReplayProof flag
- **LatticeStore**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/LatticeStore.cs` -- subject state storage and claim aggregation
- **DispositionSelector**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/DispositionSelector.cs` -- applies policy rules to select final disposition
- **ConflictPenalizer**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/ConflictPenalizer.cs` -- applies configurable penalties to conflicting claims
- **SecurityAtom**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/SecurityAtom.cs` -- atomic propositions (Present, Applies, Reachable, Mitigated, Fixed, Misattributed)
- **VEX Normalizers**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/VexNormalizers.cs`, `OpenVexNormalizer.cs`, `CsafVexNormalizer.cs` -- normalize CycloneDX, OpenVEX, CSAF formats to claims
- **TrustLabel**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/TrustLabel.cs` -- trust level annotations for claims
- **PolicyBundle / ProofBundle**: `src/Policy/__Libraries/StellaOps.Policy/TrustLattice/PolicyBundle.cs`, `ProofBundle.cs` -- policy configuration and proof bundles with decision traces

## E2E Test Plan
- [ ] Create TrustLatticeEngine with default policy; ingest two claims with True and False assertions for same subject; verify K4 value is Conflict
- [ ] Ingest claims from OpenVEX, CycloneDX, and CSAF documents; verify all three normalizers produce valid claims in the LatticeStore
- [ ] Verify Join commutativity: `Join(a, b) == Join(b, a)` for all K4Value combinations
- [ ] Verify Join idempotency: `Join(a, a) == a` for all K4Value values
- [ ] Verify Meet/Join absorption: `Join(a, Meet(a, b)) == a` for all K4Value combinations
- [ ] Verify conflict penalization: merge two claims with different VEX statuses; winning claim has lower adjusted score than original when conflict detected
- [ ] Verify `RequiresReplayProof` is set when `RequireReplayProofOnConflict=true` and conflicts exist
- [ ] Evaluate all subjects with `GenerateProofBundle=true` and verify proof bundle contains atom tables, claims, and decisions
- [ ] Verify subject filter: evaluate with SubjectFilter containing one digest; only that subject's disposition is returned
- [ ] Verify ClaimBuilder fluent API: create claim with `Present().Reachable().Mitigated()` and verify three assertions are ingested