49 lines
3.6 KiB
Markdown
49 lines
3.6 KiB
Markdown
# 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
|