stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

DET-001/002/003: Add IGuidProvider abstraction and refactor Policy.Unknowns for determinism

Browse Source 
- Created IGuidProvider interface and SystemGuidProvider in StellaOps.Determinism.Abstractions
- Added SequentialGuidProvider for testing deterministic GUID generation
- Added DeterminismServiceCollectionExtensions with AddDeterminismDefaults()
- Refactored Policy.Unknowns:
  - UnknownsRepository now uses TimeProvider and IGuidProvider
  - BudgetExceededEventFactory accepts optional TimeProvider parameter
  - ServiceCollectionExtensions calls AddDeterminismDefaults()
- Fixed Policy.Exceptions csproj (added ImplicitUsings, Nullable, PackageReferences)

Sprint: SPRINT_20260104_001_BE_determinism_timeprovider_injection
Tasks: DET-001 (audit), DET-002 (IGuidProvider), DET-003 (registration pattern), DET-004 (partial - Policy.Unknowns)
This commit is contained in:
StellaOps Bot
2026-01-04 12:37:12 +02:00
parent 3130cdb702
commit cb898a4ac8
9 changed files with 151 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
docs/implplan/SPRINT_20260104_001_BE_determinism_timeprovider_injection.md
View File

@@ -54,10 +54,10 @@
| # | Task ID | Status | Key dependency / next step | Owners | Task Definition |
| --- | --- | --- | --- | --- | --- |
| 1 | DET-001 | TODO | Audit complete | Guild | Full audit: count all DateTimeOffset.UtcNow/DateTime.UtcNow/Guid.NewGuid/Random.Shared by project |
| 2 | DET-002 | TODO | DET-001 | Guild | Ensure IGuidProvider abstraction exists in StellaOps.Determinism.Abstractions |
| 3 | DET-003 | TODO | DET-001 | Guild | Ensure TimeProvider registration pattern documented |
| 4 | DET-004 | TODO | DET-002, DET-003 | Guild | Refactor Policy module (Policy.Unknowns, PolicyDsl, etc.) |
| 1 | DET-001 | DONE | Audit complete | Guild | Full audit: count all DateTimeOffset.UtcNow/DateTime.UtcNow/Guid.NewGuid/Random.Shared by project |
| 2 | DET-002 | DONE | DET-001 | Guild | Ensure IGuidProvider abstraction exists in StellaOps.Determinism.Abstractions |
| 3 | DET-003 | DONE | DET-001 | Guild | Ensure TimeProvider registration pattern documented |
| 4 | DET-004 | DOING | DET-002, DET-003 | Guild | Refactor Policy module (Policy.Unknowns, PolicyDsl, etc.) |
| 5 | DET-005 | TODO | DET-002, DET-003 | Guild | Refactor Provcache module |
| 6 | DET-006 | TODO | DET-002, DET-003 | Guild | Refactor Provenance module |
| 7 | DET-007 | TODO | DET-002, DET-003 | Guild | Refactor ReachGraph module |
@@ -110,6 +110,11 @@ services.AddSingleton<IGuidProvider, SystemGuidProvider>();
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-01-04 | Sprint created; deferred from SPRINT_20251229_049_BE MAINT tasks | Planning |
| 2026-01-04 | DET-001: Audit complete. Found 1526 DateTimeOffset.UtcNow, 181 DateTime.UtcNow, 687 Guid.NewGuid, 16 Random.Shared | Agent |
| 2026-01-04 | DET-002: Created IGuidProvider, SystemGuidProvider, SequentialGuidProvider in StellaOps.Determinism.Abstractions | Agent |
| 2026-01-04 | DET-003: Created DeterminismServiceCollectionExtensions with AddDeterminismDefaults() | Agent |
| 2026-01-04 | DET-004: Policy.Unknowns refactored - UnknownsRepository, BudgetExceededEventFactory, ServiceCollectionExtensions | Agent |
| 2026-01-04 | Fixed Policy.Exceptions csproj - added ImplicitUsings, Nullable, PackageReferences | Agent |
## Decisions & Risks
- **Decision:** Defer determinism refactoring from MAINT audit to dedicated sprint for focused, systematic approach.

7
src/Policy/__Libraries/StellaOps.Policy.Exceptions/StellaOps.Policy.Exceptions.csproj
View File

@@ -1,6 +1,8 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
<PackageId>StellaOps.Policy.Exceptions</PackageId>
<Authors>StellaOps</Authors>
@@ -12,4 +14,9 @@
<IncludeSource>false</IncludeSource>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
<PackageReference Include="Npgsql" />
</ItemGroup>
</Project>

10
src/Policy/__Libraries/StellaOps.Policy.Unknowns/Events/BudgetExceededEventFactory.cs
View File

@@ -29,9 +29,15 @@ public static class BudgetExceededEventFactory
/// <summary>
/// Creates a budget exceeded notification event payload.
/// </summary>
/// <param name="environment">The environment name.</param>
/// <param name="result">The budget check result.</param>
/// <param name="timeProvider">Time provider for timestamp. Uses system time if null.</param>
/// <param name="imageDigest">Optional image digest.</param>
/// <param name="policyRevisionId">Optional policy revision ID.</param>
public static BudgetEventPayload CreatePayload(
string environment,
BudgetCheckResult result,
TimeProvider? timeProvider = null,
string? imageDigest = null,
string? policyRevisionId = null)
{
@@ -57,7 +63,7 @@ public static class BudgetExceededEventFactory
Message = result.Message,
ImageDigest = imageDigest,
PolicyRevisionId = policyRevisionId,
Timestamp = DateTimeOffset.UtcNow
Timestamp = (timeProvider ?? TimeProvider.System).GetUtcNow()
};
}
@@ -198,7 +204,7 @@ public sealed record BudgetEventPayload
/// <summary>
/// Event timestamp.
/// </summary>
public DateTimeOffset Timestamp { get; init; } = DateTimeOffset.UtcNow;
public DateTimeOffset Timestamp { get; init; }
}
/// <summary>

23
src/Policy/__Libraries/StellaOps.Policy.Unknowns/Repositories/UnknownsRepository.cs
View File

@@ -1,6 +1,7 @@
using System.Data;
using System.Text.Json;
using Dapper;
using StellaOps.Determinism;
using StellaOps.Policy.Unknowns.Models;
namespace StellaOps.Policy.Unknowns.Repositories;
@@ -15,9 +16,15 @@ namespace StellaOps.Policy.Unknowns.Repositories;
public sealed class UnknownsRepository : IUnknownsRepository
{
private readonly IDbConnection _connection;
private readonly TimeProvider _timeProvider;
private readonly IGuidProvider _guidProvider;
public UnknownsRepository(IDbConnection connection)
=> _connection = connection ?? throw new ArgumentNullException(nameof(connection));
public UnknownsRepository(IDbConnection connection, TimeProvider timeProvider, IGuidProvider guidProvider)
{
_connection = connection ?? throw new ArgumentNullException(nameof(connection));
_timeProvider = timeProvider ?? throw new ArgumentNullException(nameof(timeProvider));
_guidProvider = guidProvider ?? throw new ArgumentNullException(nameof(guidProvider));
}
/// <inheritdoc />
public async Task<Unknown?> GetByIdAsync(Guid tenantId, Guid id, CancellationToken cancellationToken = default)
@@ -162,8 +169,8 @@ public sealed class UnknownsRepository : IUnknownsRepository
/// <inheritdoc />
public async Task<Unknown> CreateAsync(Unknown unknown, CancellationToken cancellationToken = default)
{
var id = unknown.Id == Guid.Empty ? Guid.NewGuid() : unknown.Id;
var now = DateTimeOffset.UtcNow;
var id = unknown.Id == Guid.Empty ? _guidProvider.NewGuid() : unknown.Id;
var now = _timeProvider.GetUtcNow();
const string sql = """
SELECT set_config('app.current_tenant', @TenantId::text, true);
@@ -258,7 +265,7 @@ public sealed class UnknownsRepository : IUnknownsRepository
WHERE id = @Id;
""";
var evaluatedAt = DateTimeOffset.UtcNow;
var evaluatedAt = _timeProvider.GetUtcNow();
var param = new
{
unknown.TenantId,
@@ -304,7 +311,7 @@ public sealed class UnknownsRepository : IUnknownsRepository
WHERE id = @Id;
""";
var now = DateTimeOffset.UtcNow;
var now = _timeProvider.GetUtcNow();
var param = new
{
TenantId = tenantId,
@@ -324,7 +331,7 @@ public sealed class UnknownsRepository : IUnknownsRepository
IEnumerable<Unknown> unknowns,
CancellationToken cancellationToken = default)
{
var now = DateTimeOffset.UtcNow;
var now = _timeProvider.GetUtcNow();
var total = 0;
const string sql = """
@@ -370,7 +377,7 @@ public sealed class UnknownsRepository : IUnknownsRepository
foreach (var unknown in unknowns)
{
var id = unknown.Id == Guid.Empty ? Guid.NewGuid() : unknown.Id;
var id = unknown.Id == Guid.Empty ? _guidProvider.NewGuid() : unknown.Id;
var param = new
{
Id = id,

4
src/Policy/__Libraries/StellaOps.Policy.Unknowns/ServiceCollectionExtensions.cs
View File

@@ -1,4 +1,5 @@
using Microsoft.Extensions.DependencyInjection;
using StellaOps.Determinism;
using StellaOps.Policy.Unknowns.Configuration;
using StellaOps.Policy.Unknowns.Repositories;
using StellaOps.Policy.Unknowns.Services;
@@ -27,6 +28,9 @@ public static class ServiceCollectionExtensions
if (configureBudgetOptions is not null)
services.Configure(configureBudgetOptions);
// Ensure determinism dependencies are registered
services.AddDeterminismDefaults();
// Register services
services.AddSingleton<IUnknownBudgetService, UnknownBudgetService>();
services.AddSingleton<IRemediationHintsRegistry, RemediationHintsRegistry>();

1
src/Policy/__Libraries/StellaOps.Policy.Unknowns/StellaOps.Policy.Unknowns.csproj
View File

@@ -18,6 +18,7 @@
<ItemGroup>
<ProjectReference Include="..\StellaOps.Policy.Exceptions\StellaOps.Policy.Exceptions.csproj" />
<ProjectReference Include="..\StellaOps.Policy\StellaOps.Policy.csproj" />
<ProjectReference Include="..\..\..\__Libraries\StellaOps.Determinism.Abstractions\StellaOps.Determinism.Abstractions.csproj" />
</ItemGroup>
</Project>

39
src/__Libraries/StellaOps.Determinism.Abstractions/DeterminismServiceCollectionExtensions.cs Normal file
View File

@@ -0,0 +1,39 @@
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.DependencyInjection.Extensions;
namespace StellaOps.Determinism;
/// <summary>
/// Extension methods for registering determinism abstractions in DI.
/// </summary>
public static class DeterminismServiceCollectionExtensions
{
/// <summary>
/// Adds <see cref="TimeProvider.System"/> as a singleton.
/// </summary>
public static IServiceCollection AddSystemTimeProvider(this IServiceCollection services)
{
services.TryAddSingleton(TimeProvider.System);
return services;
}
/// <summary>
/// Adds <see cref="SystemGuidProvider"/> as the <see cref="IGuidProvider"/> singleton.
/// </summary>
public static IServiceCollection AddSystemGuidProvider(this IServiceCollection services)
{
services.TryAddSingleton<IGuidProvider, SystemGuidProvider>();
return services;
}
/// <summary>
/// Adds both <see cref="TimeProvider.System"/> and <see cref="SystemGuidProvider"/> as singletons.
/// This is the recommended setup for production services.
/// </summary>
public static IServiceCollection AddDeterminismDefaults(this IServiceCollection services)
{
services.AddSystemTimeProvider();
services.AddSystemGuidProvider();
return services;
}
}

64
src/__Libraries/StellaOps.Determinism.Abstractions/IGuidProvider.cs Normal file
View File

@@ -0,0 +1,64 @@
namespace StellaOps.Determinism;
/// <summary>
/// Abstraction for GUID generation to support deterministic testing.
/// Inject this instead of using <see cref="Guid.NewGuid"/> directly.
/// </summary>
public interface IGuidProvider
{
/// <summary>
/// Generates a new GUID.
/// </summary>
Guid NewGuid();
}
/// <summary>
/// Default implementation using <see cref="Guid.NewGuid"/>.
/// Register as singleton in DI: <c>services.AddSingleton&lt;IGuidProvider, SystemGuidProvider&gt;();</c>
/// </summary>
public sealed class SystemGuidProvider : IGuidProvider
{
/// <summary>
/// Shared instance for non-DI scenarios.
/// </summary>
public static readonly SystemGuidProvider Instance = new();
/// <inheritdoc />
public Guid NewGuid() => Guid.NewGuid();
}
/// <summary>
/// Deterministic GUID provider for testing. Returns GUIDs in a predictable sequence.
/// </summary>
public sealed class SequentialGuidProvider : IGuidProvider
{
private int _counter;
private readonly Guid _baseGuid;
/// <summary>
/// Creates a sequential GUID provider starting from a base GUID.
/// </summary>
/// <param name="baseGuid">Optional base GUID. Defaults to all zeros.</param>
public SequentialGuidProvider(Guid? baseGuid = null)
{
_baseGuid = baseGuid ?? Guid.Empty;
}
/// <inheritdoc />
public Guid NewGuid()
{
var bytes = _baseGuid.ToByteArray();
var counter = Interlocked.Increment(ref _counter);
// Embed counter in last 4 bytes
bytes[12] = (byte)(counter >> 24);
bytes[13] = (byte)(counter >> 16);
bytes[14] = (byte)(counter >> 8);
bytes[15] = (byte)counter;
return new Guid(bytes);
}
/// <summary>
/// Resets the counter to zero.
/// </summary>
public void Reset() => Interlocked.Exchange(ref _counter, 0);
}

4
src/__Libraries/StellaOps.Determinism.Abstractions/StellaOps.Determinism.Abstractions.csproj
View File

@@ -9,4 +9,8 @@
<Description>Attributes and abstractions for determinism enforcement in StellaOps.</Description>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
</ItemGroup>
</Project>