Skip to content

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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.md
index 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.md
index 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