# Determinism Guards (Runtime Enforcement)

## Module
Policy

## Status
IMPLEMENTED

## Description
Runtime enforcement of determinism constraints during policy evaluation. Prohibited pattern analysis detects wall-clock, RNG, and network usage. A guarded evaluator wraps the policy engine.

## Implementation Details
- **DeterminismGuardService**: `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/DeterminismGuardService.cs` -- `DeterminismGuardService` (sealed class)
  - `AnalyzeSource(sourceCode, fileName?)` performs static analysis for determinism violations
  - `CreateScope(scopeId, evaluationTimestamp)` creates a guarded execution scope with frozen time
  - `ValidateContext<TContext>(context, contextName)` validates evaluation context for determinism
  - Combines static analysis (`ProhibitedPatternAnalyzer`) and runtime monitoring (`RuntimeDeterminismMonitor`)
  - `DeterminismGuardOptions.Default` provides default configuration
  - `EnforcementEnabled` controls whether violations cause failures or just warnings
  - `FailOnSeverity` threshold for when violations become blocking
- **ProhibitedPatternAnalyzer**: `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/ProhibitedPatternAnalyzer.cs` -- static code analysis
  - Regex-based pattern detection on source code lines
  - Detects: wall-clock access (DateTime.Now, DateTimeOffset.Now), RNG usage (Random, Guid.NewGuid), network calls, file I/O
  - Line-by-line scanning with line number tracking
  - Skips comments (// and /* ... */)
  - Reports: violation category, type, message, source file, line number, member context, severity, remediation
  - File exclusion via `ExcludePatterns` in options
  - `DeterminismViolationCategory`: WallClock, RandomNumber, NetworkAccess, FileSystem, Other
  - `DeterminismViolationSeverity` enumeration for graduated enforcement
- **GuardedPolicyEvaluator**: `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/GuardedPolicyEvaluator.cs` -- wraps policy evaluator with determinism checks
  - Pre-evaluation: validates context and checks for violations
  - Post-evaluation: verifies no runtime determinism violations occurred during evaluation
- **DeterminismViolation**: `src/Policy/StellaOps.Policy.Engine/DeterminismGuard/DeterminismViolation.cs` -- violation model
  - Category, ViolationType, Message, SourceFile, LineNumber, MemberName, Severity, Remediation
- **DeterminismAnalysisResult**: Passed (bool), Violations (ImmutableArray), CountBySeverity, AnalysisDurationMs, EnforcementEnabled
- **Verification Endpoints**: `src/Policy/StellaOps.Policy.Engine/Endpoints/VerifyDeterminismEndpoints.cs` -- REST API for determinism verification

## E2E Test Plan
- [ ] Analyze source code with `DateTime.Now` usage; verify WallClock violation detected with line number and remediation suggestion
- [ ] Analyze source code with `Random()` usage; verify RandomNumber violation detected
- [ ] Analyze clean source code (using TimeProvider, IGuidProvider); verify no violations and Passed=true
- [ ] Analyze source code with violations in comments; verify comments are skipped and no false positives
- [ ] Create guarded scope with frozen timestamp; verify evaluation uses frozen time not wall clock
- [ ] Evaluate with GuardedPolicyEvaluator; verify pre-evaluation and post-evaluation determinism checks pass
- [ ] Set EnforcementEnabled=false; verify violations are reported but Passed=true
- [ ] Set FailOnSeverity=Error; verify Warning-level violations do not cause failure
- [ ] POST to determinism verification endpoint with policy source; verify analysis result with violation counts by severity
- [ ] Analyze with ExcludePatterns matching test files; verify excluded files are skipped