stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
1bf6bbf3955ecbd8d20f5eeb767da5c7f8324b57
git.stella-ops.org/docs/features/unchecked/policy/determinism-guards.md

3.6 KiB
Raw Blame History

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