Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add kernel diagnostics and result backbone for M01
Yuechen Liad3aab4ffcaa
diff --git a/Aetheris.Kernel.Core.Tests/DiagnosticsTests.cs b/Aetheris.Kernel.Core.Tests/DiagnosticsTests.csnew file mode 100644index 00000000..d91d0dbf--- /dev/null+++ b/Aetheris.Kernel.Core.Tests/DiagnosticsTests.cs@@ -0,0 +1,36 @@+using Aetheris.Kernel.Core.Diagnostics;++namespace Aetheris.Kernel.Core.Tests;++public sealed class DiagnosticsTests+{+ [Fact]+ public void CanCreateDiagnostic_WithCodeSeverityMessageAndSource()+ {+ var diagnostic = new KernelDiagnostic(+ KernelDiagnosticCode.InvalidArgument,+ KernelDiagnosticSeverity.Warning,+ "Input radius was clamped.",+ "FakeOperation");++ Assert.Equal(KernelDiagnosticCode.InvalidArgument, diagnostic.Code);+ Assert.Equal(KernelDiagnosticSeverity.Warning, diagnostic.Severity);+ Assert.Equal("Input radius was clamped.", diagnostic.Message);+ Assert.Equal("FakeOperation", diagnostic.Source);+ }++ [Fact]+ public void DiagnosticIsImmutable_RecordWithExpressionCreatesNewInstance()+ {+ var original = new KernelDiagnostic(+ KernelDiagnosticCode.Unknown,+ KernelDiagnosticSeverity.Info,+ "Original message");++ var changed = original with { Message = "Changed message" };++ Assert.Equal("Original message", original.Message);+ Assert.Equal("Changed message", changed.Message);+ Assert.NotEqual(original, changed);+ }+}diff --git a/Aetheris.Kernel.Core.Tests/KernelResultTests.cs b/Aetheris.Kernel.Core.Tests/KernelResultTests.csnew file mode 100644index 00000000..6dca87e9--- /dev/null+++ b/Aetheris.Kernel.Core.Tests/KernelResultTests.cs@@ -0,0 +1,120 @@+using Aetheris.Kernel.Core.Diagnostics;+using Aetheris.Kernel.Core.Results;++namespace Aetheris.Kernel.Core.Tests;++public sealed class KernelResultTests+{+ [Fact]+ public void SuccessResult_ExposesValueAndIsSuccessTrue()+ {+ var result = FakeOperation(success: true);++ Assert.True(result.IsSuccess);+ Assert.Equal(42, result.Value);+ }++ [Fact]+ public void SuccessResult_CanCarryWarningOrInfoDiagnostics()+ {+ var result = FakeOperation(+ success: true,+ diagnostics:+ [+ new KernelDiagnostic(KernelDiagnosticCode.Unknown, KernelDiagnosticSeverity.Info, "FYI"),+ new KernelDiagnostic(KernelDiagnosticCode.ValidationFailed, KernelDiagnosticSeverity.Warning, "Something to review"),+ ]);++ Assert.True(result.IsSuccess);+ Assert.Equal(2, result.Diagnostics.Count);+ Assert.DoesNotContain(result.Diagnostics, d => d.Severity == KernelDiagnosticSeverity.Error);+ }++ [Fact]+ public void FailureResult_HasIsSuccessFalseAndErrorDiagnostic()+ {+ var result = FakeOperation(+ success: false,+ diagnostics:+ [+ new KernelDiagnostic(KernelDiagnosticCode.InvalidArgument, KernelDiagnosticSeverity.Error, "Input invalid")+ ]);++ Assert.False(result.IsSuccess);+ Assert.Contains(result.Diagnostics, d => d.Severity == KernelDiagnosticSeverity.Error);+ }++ [Fact]+ public void FailureResult_ValueAccessThrowsAndTryGetValueReturnsFalse()+ {+ var result = FakeOperation(success: false);++ var exception = Assert.Throws<InvalidOperationException>(() => _ = result.Value);+ Assert.Equal("Cannot access Value when the result is a failure.", exception.Message);++ var gotValue = result.TryGetValue(out var value);++ Assert.False(gotValue);+ Assert.Equal(default, value);+ }++ [Fact]+ public void DiagnosticsCollection_CannotBeMutatedExternally()+ {+ var sourceDiagnostics = new List<KernelDiagnostic>+ {+ new(KernelDiagnosticCode.Unknown, KernelDiagnosticSeverity.Warning, "before")+ };++ var result = KernelResult<int>.Success(1, sourceDiagnostics);+ sourceDiagnostics.Add(new KernelDiagnostic(KernelDiagnosticCode.Unknown, KernelDiagnosticSeverity.Warning, "after"));++ Assert.Single(result.Diagnostics);+ }++ [Fact]+ public void CreatingSuccessWithErrorDiagnostic_IsRejected()+ {+ var diagnostics = new[]+ {+ new KernelDiagnostic(KernelDiagnosticCode.InternalError, KernelDiagnosticSeverity.Error, "nope"),+ };++ var exception = Assert.Throws<ArgumentException>(() => KernelResult<int>.Success(1, diagnostics));++ Assert.Equal("diagnostics", exception.ParamName);+ }++ [Fact]+ public void CreatingFailureWithNoDiagnostics_AutoPopulatesInternalError()+ {+ var result = KernelResult<int>.Failure();++ Assert.False(result.IsSuccess);+ Assert.Single(result.Diagnostics);+ Assert.Equal(KernelDiagnosticCode.InternalError, result.Diagnostics[0].Code);+ Assert.Equal(KernelDiagnosticSeverity.Error, result.Diagnostics[0].Severity);+ }++ [Fact]+ public void CreatingFailureWithoutErrorDiagnostic_NormalizesByAppendingInternalError()+ {+ var result = KernelResult<int>.Failure(+ [+ new KernelDiagnostic(KernelDiagnosticCode.ValidationFailed, KernelDiagnosticSeverity.Warning, "warning only")+ ]);++ Assert.Equal(2, result.Diagnostics.Count);+ Assert.Contains(result.Diagnostics, d => d.Severity == KernelDiagnosticSeverity.Error && d.Code == KernelDiagnosticCode.InternalError);+ }++ private static KernelResult<int> FakeOperation(bool success, IReadOnlyList<KernelDiagnostic>? diagnostics = null)+ {+ if (success)+ {+ return KernelResult<int>.Success(42, diagnostics);+ }++ return KernelResult<int>.Failure(diagnostics);+ }+}diff --git a/Aetheris.Kernel.Core/Diagnostics/KernelDiagnostic.cs b/Aetheris.Kernel.Core/Diagnostics/KernelDiagnostic.csnew file mode 100644index 00000000..55cb0cb1--- /dev/null+++ b/Aetheris.Kernel.Core/Diagnostics/KernelDiagnostic.cs@@ -0,0 +1,7 @@+namespace Aetheris.Kernel.Core.Diagnostics;++public sealed record KernelDiagnostic(+ KernelDiagnosticCode Code,+ KernelDiagnosticSeverity Severity,+ string Message,+ string? Source = null);diff --git a/Aetheris.Kernel.Core/Diagnostics/KernelDiagnosticCode.cs b/Aetheris.Kernel.Core/Diagnostics/KernelDiagnosticCode.csnew file mode 100644index 00000000..28a788b0--- /dev/null+++ b/Aetheris.Kernel.Core/Diagnostics/KernelDiagnosticCode.cs@@ -0,0 +1,11 @@+namespace Aetheris.Kernel.Core.Diagnostics;++public enum KernelDiagnosticCode+{+ Unknown,+ InvalidArgument,+ NotImplemented,+ InternalError,+ ValidationFailed,+ ToleranceConflict,+}diff --git a/Aetheris.Kernel.Core/Diagnostics/KernelDiagnosticSeverity.cs b/Aetheris.Kernel.Core/Diagnostics/KernelDiagnosticSeverity.csnew file mode 100644index 00000000..5157a551--- /dev/null+++ b/Aetheris.Kernel.Core/Diagnostics/KernelDiagnosticSeverity.cs@@ -0,0 +1,8 @@+namespace Aetheris.Kernel.Core.Diagnostics;++public enum KernelDiagnosticSeverity+{+ Info,+ Warning,+ Error,+}diff --git a/Aetheris.Kernel.Core/Results/KernelResult.cs b/Aetheris.Kernel.Core/Results/KernelResult.csnew file mode 100644index 00000000..8b04f2af--- /dev/null+++ b/Aetheris.Kernel.Core/Results/KernelResult.cs@@ -0,0 +1,89 @@+using Aetheris.Kernel.Core.Diagnostics;++namespace Aetheris.Kernel.Core.Results;++public sealed class KernelResult<T>+{+ private static readonly IReadOnlyList<KernelDiagnostic> EmptyDiagnostics = Array.Empty<KernelDiagnostic>();++ private readonly T? _value;++ private KernelResult(bool isSuccess, T? value, IReadOnlyList<KernelDiagnostic> diagnostics)+ {+ IsSuccess = isSuccess;+ _value = value;+ Diagnostics = diagnostics;+ }++ public bool IsSuccess { get; }++ public IReadOnlyList<KernelDiagnostic> Diagnostics { get; }++ public T Value => IsSuccess+ ? _value!+ : throw new InvalidOperationException("Cannot access Value when the result is a failure.");++ public static KernelResult<T> Success(T value, IEnumerable<KernelDiagnostic>? diagnostics = null)+ {+ var materializedDiagnostics = MaterializeDiagnostics(diagnostics);++ if (materializedDiagnostics.Any(d => d.Severity == KernelDiagnosticSeverity.Error))+ {+ throw new ArgumentException("Success results cannot include Error diagnostics.", nameof(diagnostics));+ }++ return new KernelResult<T>(isSuccess: true, value, materializedDiagnostics);+ }++ public static KernelResult<T> Failure(IEnumerable<KernelDiagnostic>? diagnostics = null)+ {+ var materializedDiagnostics = MaterializeDiagnostics(diagnostics);++ if (materializedDiagnostics.Count == 0)+ {+ materializedDiagnostics =+ [+ new KernelDiagnostic(+ KernelDiagnosticCode.InternalError,+ KernelDiagnosticSeverity.Error,+ "Operation failed without explicit diagnostics.")+ ];+ }+ else if (!materializedDiagnostics.Any(d => d.Severity == KernelDiagnosticSeverity.Error))+ {+ materializedDiagnostics =+ [+ .. materializedDiagnostics,+ new KernelDiagnostic(+ KernelDiagnosticCode.InternalError,+ KernelDiagnosticSeverity.Error,+ "Operation failed without an Error diagnostic; an InternalError diagnostic was added.")+ ];+ }++ return new KernelResult<T>(isSuccess: false, value: default, materializedDiagnostics);+ }++ public bool TryGetValue(out T value)+ {+ if (IsSuccess)+ {+ value = _value!;+ return true;+ }++ value = default!;+ return false;+ }++ private static IReadOnlyList<KernelDiagnostic> MaterializeDiagnostics(IEnumerable<KernelDiagnostic>? diagnostics)+ {+ if (diagnostics is null)+ {+ return EmptyDiagnostics;+ }++ var list = diagnostics.ToArray();+ return list;+ }+}diff --git a/docs/architecture-overview.md b/docs/architecture-overview.mdindex 459c8152..503ea36d 100644--- a/docs/architecture-overview.md+++ b/docs/architecture-overview.md@@ -15,3 +15,4 @@ This package map is directional only and may evolve with milestone outcomes.- Boundaries are favored over deep abstraction in early milestones.- Kernel remains independent from UI and persistence concerns.+- Kernel operations should return structured result/diagnostic envelopes for expected outcomes instead of throwing ad hoc exceptions.diff --git a/docs/milestones.md b/docs/milestones.mdindex 772ef932..36b12e26 100644--- a/docs/milestones.md+++ b/docs/milestones.md@@ -9,9 +9,10 @@## M01 — Diagnostics and Result Model Baseline-- [ ] Define kernel operation result envelope (success/failure + diagnostics).-- [ ] Introduce shared diagnostic identifiers and deterministic formatting conventions.-- [ ] Add tests for result model semantics.+- [x] Define a kernel operation result envelope (`KernelResult<T>`) for success/failure with diagnostics.+- [x] Introduce shared kernel diagnostic primitives (severity + stable codes + immutable payload).+- [x] Enforce guardrails for success/failure diagnostic shape (no success errors, failure has at least one error).+- [x] Add focused unit tests that lock result/diagnostic semantics.## M02 — Tolerance and Numerics Primitives