Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add canonical STEP SHA256 hash to export API and UI

Yuechen Lieea3e22cde06
diff --git a/Aetheris.Server.Tests/KernelApiIntegrationTests.cs b/Aetheris.Server.Tests/KernelApiIntegrationTests.cs
index 53be7aea..e85c2f9a 100644
--- a/Aetheris.Server.Tests/KernelApiIntegrationTests.cs
+++ b/Aetheris.Server.Tests/KernelApiIntegrationTests.cs
@@ -357,6 +357,8 @@ public sealed class KernelApiIntegrationTests : IClassFixture<WebApplicationFact
Assert.NotNull(exported.Data);
Assert.Contains("ISO-10303-21", exported.Data!.StepText);
Assert.Contains("MANIFOLD_SOLID_BREP", exported.Data.StepText);
+ Assert.False(string.IsNullOrWhiteSpace(exported.Data.CanonicalHash));
+ Assert.Equal(64, exported.Data.CanonicalHash.Length);
var importResponse = await _client.PostAsJsonAsync(
$"/api/v1/documents/{document.Data.DocumentId}/import/step",
@@ -382,6 +384,71 @@ public sealed class KernelApiIntegrationTests : IClassFixture<WebApplicationFact
Assert.NotEmpty(tessellation.Data.EdgePolylines);
}
+
+ [Fact]
+ public async Task StepExport_Twice_ReturnsDeterministicTextAndHash()
+ {
+ var document = await CreateDocumentAsync("/api/v1/documents");
+ var box = await CreateBoxAsync("/api/v1/documents", document.Data!.DocumentId, 2, 2, 2);
+
+ var firstResponse = await _client.GetAsync($"/api/v1/documents/{document.Data.DocumentId}/definitions/{box.Data!.DefinitionId}/export/step");
+ firstResponse.EnsureSuccessStatusCode();
+ var first = await firstResponse.Content.ReadFromJsonAsync<ApiResponseDto<StepExportResponseDto>>();
+
+ var secondResponse = await _client.GetAsync($"/api/v1/documents/{document.Data.DocumentId}/definitions/{box.Data.DefinitionId}/export/step");
+ secondResponse.EnsureSuccessStatusCode();
+ var second = await secondResponse.Content.ReadFromJsonAsync<ApiResponseDto<StepExportResponseDto>>();
+
+ Assert.NotNull(first);
+ Assert.NotNull(second);
+ Assert.Equal(first!.Data!.StepText, second!.Data!.StepText);
+ Assert.Equal(first.Data.CanonicalHash, second.Data.CanonicalHash);
+ }
+
+ [Fact]
+ public async Task StepExport_ImportThenExport_ProducesStableCanonicalHash()
+ {
+ var document = await CreateDocumentAsync("/api/v1/documents");
+ var box = await CreateBoxAsync("/api/v1/documents", document.Data!.DocumentId, 2, 2, 2);
+
+ var exportResponse = await _client.GetAsync($"/api/v1/documents/{document.Data.DocumentId}/definitions/{box.Data!.DefinitionId}/export/step");
+ exportResponse.EnsureSuccessStatusCode();
+ var exported = await exportResponse.Content.ReadFromJsonAsync<ApiResponseDto<StepExportResponseDto>>();
+
+ var importResponse = await _client.PostAsJsonAsync(
+ $"/api/v1/documents/{document.Data.DocumentId}/import/step",
+ new StepImportRequestDto(exported!.Data!.StepText, "Imported Hash Test"));
+ importResponse.EnsureSuccessStatusCode();
+ var imported = await importResponse.Content.ReadFromJsonAsync<ApiResponseDto<StepImportResponseDto>>();
+
+ var importedExportResponse = await _client.GetAsync($"/api/v1/documents/{document.Data.DocumentId}/definitions/{imported!.Data!.DefinitionId}/export/step");
+ importedExportResponse.EnsureSuccessStatusCode();
+ var importedExport = await importedExportResponse.Content.ReadFromJsonAsync<ApiResponseDto<StepExportResponseDto>>();
+
+ Assert.NotNull(importedExport);
+ Assert.Equal(exported.Data.CanonicalHash, importedExport!.Data!.CanonicalHash);
+ }
+
+ [Fact]
+ public async Task StepExport_HashChangesForDifferentGeometry()
+ {
+ var document = await CreateDocumentAsync("/api/v1/documents");
+ var firstBox = await CreateBoxAsync("/api/v1/documents", document.Data!.DocumentId, 2, 2, 2);
+ var secondBox = await CreateBoxAsync("/api/v1/documents", document.Data.DocumentId, 3, 2, 2);
+
+ var firstExportResponse = await _client.GetAsync($"/api/v1/documents/{document.Data.DocumentId}/definitions/{firstBox.Data!.DefinitionId}/export/step");
+ firstExportResponse.EnsureSuccessStatusCode();
+ var firstExport = await firstExportResponse.Content.ReadFromJsonAsync<ApiResponseDto<StepExportResponseDto>>();
+
+ var secondExportResponse = await _client.GetAsync($"/api/v1/documents/{document.Data.DocumentId}/definitions/{secondBox.Data!.DefinitionId}/export/step");
+ secondExportResponse.EnsureSuccessStatusCode();
+ var secondExport = await secondExportResponse.Content.ReadFromJsonAsync<ApiResponseDto<StepExportResponseDto>>();
+
+ Assert.NotNull(firstExport);
+ Assert.NotNull(secondExport);
+ Assert.NotEqual(firstExport!.Data!.CanonicalHash, secondExport!.Data!.CanonicalHash);
+ }
+
[Fact]
public async Task StepImport_EmptyText_ReturnsBadRequestEnvelope()
{
diff --git a/Aetheris.Server/Api/KernelEndpoints.cs b/Aetheris.Server/Api/KernelEndpoints.cs
index e3db050b..b8c511cb 100644
--- a/Aetheris.Server/Api/KernelEndpoints.cs
+++ b/Aetheris.Server/Api/KernelEndpoints.cs
@@ -7,6 +7,8 @@ using Aetheris.Kernel.Core.Math;
using Aetheris.Kernel.Core.Step242;
using Aetheris.Server.Contracts;
using Aetheris.Server.Documents;
+using System.Security.Cryptography;
+using System.Text;
namespace Aetheris.Server.Api;
@@ -231,7 +233,9 @@ public static class KernelEndpoints
return ApiMappings.KernelFailure(exportResult.Diagnostics);
}
- return ApiMappings.Ok(new StepExportResponseDto(documentId, definitionId, exportResult.Value, []));
+ var canonicalHash = ComputeCanonicalHash(exportResult.Value);
+
+ return ApiMappings.Ok(new StepExportResponseDto(documentId, definitionId, exportResult.Value, canonicalHash, []));
}));
documents.MapPost("/{documentId:guid}/import/step", (Guid documentId, StepImportRequestDto request, KernelDocumentStore store) =>
@@ -327,6 +331,13 @@ public static class KernelEndpoints
}));
}
+ private static string ComputeCanonicalHash(string stepText)
+ {
+ var utf8Bytes = Encoding.UTF8.GetBytes(stepText);
+ var hash = SHA256.HashData(utf8Bytes);
+ return Convert.ToHexString(hash).ToLowerInvariant();
+ }
+
private static IResult WithDocument(KernelDocumentStore store, Guid documentId, Func<DocumentSession, IResult> operation)
{
if (!store.TryGet(documentId, out var document))
diff --git a/Aetheris.Server/Contracts/ApiContracts.cs b/Aetheris.Server/Contracts/ApiContracts.cs
index d970ffff..edcab452 100644
--- a/Aetheris.Server/Contracts/ApiContracts.cs
+++ b/Aetheris.Server/Contracts/ApiContracts.cs
@@ -40,7 +40,7 @@ public sealed record CreateOccurrenceRequestDto(Guid? SourceOccurrenceId, Guid?
public sealed record OccurrenceCreatedResponseDto(Guid DocumentId, Guid BodyId, Guid DefinitionId, string? Name);
-public sealed record StepExportResponseDto(Guid DocumentId, Guid DefinitionId, string StepText, IReadOnlyList<DiagnosticDto> Diagnostics);
+public sealed record StepExportResponseDto(Guid DocumentId, Guid DefinitionId, string StepText, string CanonicalHash, IReadOnlyList<DiagnosticDto> Diagnostics);
public sealed record StepImportRequestDto(string? StepText, string? Name);
diff --git a/aetheris.client/src/App.css b/aetheris.client/src/App.css
index 6fdec5fc..23dc64dc 100644
--- a/aetheris.client/src/App.css
+++ b/aetheris.client/src/App.css
@@ -137,3 +137,9 @@ textarea {
background: #020617;
resize: vertical;
}
+
+.mono-value {
+ font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+ word-break: break-all;
+ user-select: all;
+}
diff --git a/aetheris.client/src/App.tsx b/aetheris.client/src/App.tsx
index 1911023b..95752a79 100644
--- a/aetheris.client/src/App.tsx
+++ b/aetheris.client/src/App.tsx
@@ -54,6 +54,7 @@ function App() {
const [stepExportText, setStepExportText] = useState('');
const [stepImportText, setStepImportText] = useState('');
const [stepImportName, setStepImportName] = useState('Imported');
+ const [stepCanonicalHash, setStepCanonicalHash] = useState<string | null>(null);
const runAction = useCallback(async (actionName: string, action: () => Promise<void>) => {
setStatus('loading');
@@ -112,6 +113,7 @@ function App() {
setStepExportText('');
setStepImportText('');
setStepImportName('Imported');
+ setStepCanonicalHash(null);
});
}, [runAction]);
@@ -207,8 +209,9 @@ function App() {
}
await runAction('Export active STEP', async () => {
- const text = await exportDefinitionStep(documentId, activeOccurrence.definitionId);
- setStepExportText(text);
+ const exported = await exportDefinitionStep(documentId, activeOccurrence.definitionId);
+ setStepExportText(exported.stepText);
+ setStepCanonicalHash(exported.canonicalHash);
});
}, [activeBodyId, documentId, occurrences, runAction]);
@@ -221,6 +224,8 @@ function App() {
const imported = await importStep(documentId, stepImportText, stepImportName.trim().length === 0 ? undefined : stepImportName.trim());
setStepExportText('');
await refreshSummaryAndActiveTessellation(imported.occurrenceId);
+ const exported = await exportDefinitionStep(documentId, imported.definitionId);
+ setStepCanonicalHash(exported.canonicalHash);
setStepImportName(imported.name ?? 'Imported');
setPickStatus('idle');
setPickMessage(`Imported occurrence ${imported.occurrenceId} is now active.`);
@@ -462,6 +467,7 @@ function App() {
<p><strong>Occurrence count:</strong> {bodyIds.length}</p>
<p><strong>Face patches:</strong> {tessellation?.facePatches.length ?? 0}</p>
<p><strong>Edge polylines:</strong> {tessellation?.edgePolylines.length ?? 0}</p>
+ <p><strong>Canonical SHA256:</strong> <code className="mono-value">{stepCanonicalHash ?? 'Not available'}</code></p>
<h3>Pick Diagnostics (active body only)</h3>
<p><strong>Pick status:</strong> {pickStatus}</p>
<p><strong>Pick message:</strong> {pickMessage}</p>
diff --git a/aetheris.client/src/__tests__/aetherisApi.test.ts b/aetheris.client/src/__tests__/aetherisApi.test.ts
index 9cbfaac9..fba418c9 100644
--- a/aetheris.client/src/__tests__/aetherisApi.test.ts
+++ b/aetheris.client/src/__tests__/aetherisApi.test.ts
@@ -168,16 +168,40 @@ describe('STEP API', () => {
documentId: 'doc-1',
definitionId: 'def-1',
stepText: 'ISO-10303-21;\nDATA;\n#1=MANIFOLD_SOLID_BREP();',
+ canonicalHash: 'abc123',
diagnostics: [],
},
diagnostics: [],
}), { status: 200 }));
vi.stubGlobal('fetch', fetchMock);
- const stepText = await exportDefinitionStep('doc-1', 'def-1');
+ const exportResponse = await exportDefinitionStep('doc-1', 'def-1');
expect(fetchMock).toHaveBeenCalledWith('/api/v1/documents/doc-1/definitions/def-1/export/step', expect.objectContaining({ method: 'GET' }));
- expect(stepText).toContain('ISO-10303-21');
+ expect(exportResponse.stepText).toContain('ISO-10303-21');
+ expect(exportResponse.canonicalHash).toBe('abc123');
+ });
+
+
+ it('propagates exportDefinitionStep diagnostics on envelope failure', async () => {
+ const fetchMock = vi.fn().mockResolvedValue(new Response(JSON.stringify({
+ success: false,
+ data: null,
+ diagnostics: [{
+ code: 'ValidationFailed',
+ severity: 'Error',
+ message: 'Unable to export STEP payload.',
+ source: 'step242.export',
+ }],
+ }), { status: 422 }));
+ vi.stubGlobal('fetch', fetchMock);
+
+ await expect(exportDefinitionStep('doc-1', 'def-1')).rejects.toEqual(new ApiError('Unable to export STEP payload.', [{
+ code: 'ValidationFailed',
+ severity: 'Error',
+ message: 'Unable to export STEP payload.',
+ source: 'step242.export',
+ }]));
});
it('parses importStep success envelope', async () => {
diff --git a/aetheris.client/src/api/aetherisApi.ts b/aetheris.client/src/api/aetherisApi.ts
index b1eea150..41afdc3e 100644
--- a/aetheris.client/src/api/aetherisApi.ts
+++ b/aetheris.client/src/api/aetherisApi.ts
@@ -53,6 +53,7 @@ export interface StepExportResponseDto {
documentId: string;
definitionId: string;
stepText: string;
+ canonicalHash: string;
diagnostics: DiagnosticDto[];
}
@@ -222,12 +223,10 @@ export async function executeBoolean(documentId: string, requestDto: BooleanRequ
});
}
-export async function exportDefinitionStep(documentId: string, definitionId: string): Promise<string> {
- const response = await request<StepExportResponseDto>(`/api/v1/documents/${documentId}/definitions/${definitionId}/export/step`, {
+export async function exportDefinitionStep(documentId: string, definitionId: string): Promise<StepExportResponseDto> {
+ return request<StepExportResponseDto>(`/api/v1/documents/${documentId}/definitions/${definitionId}/export/step`, {
method: 'GET',
});
-
- return response.stepText;
}
export async function importStep(documentId: string, stepText: string, name?: string): Promise<StepImportResponseDto> {
diff --git a/docs/milestones.md b/docs/milestones.md
index fa15ea36..ec967c6a 100644
--- a/docs/milestones.md
+++ b/docs/milestones.md
@@ -246,3 +246,11 @@
- [x] Add client API methods and explicit UI controls for button-driven STEP export/import text workflows, with imported occurrence auto-selection and tessellation refresh.
- [x] Extend client envelope tests for STEP API success parsing and failure diagnostic propagation through `ApiError`.
- [x] Defer AP242 assembly/product-structure mapping, multi-definition export, metadata completeness, and file-dialog UX to later milestones.
+
+## M27 — Canonical STEP Hash Infrastructure
+
+- [x] Compute deterministic canonical SHA256 hashes in backend STEP export responses using UTF-8 bytes of the exporter output text.
+- [x] Extend STEP export API contracts to include a backend-authoritative `canonicalHash` field.
+- [x] Add server integration coverage for determinism across repeated exports, import→export stability, and geometry-sensitive hash changes.
+- [x] Update client STEP API parsing and inspector UI display to surface `canonicalHash` with copy-friendly monospace formatting.
+- [x] Extend client API tests to validate `canonicalHash` parsing and maintain `ApiError` propagation behavior.