Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Document inline STEP probe harness for ruled tooling

Yuechen Licfeec1e59478
diff --git a/Aetheris.CLI.Tests/RuledStepProbeHarnessTests.cs b/Aetheris.CLI.Tests/RuledStepProbeHarnessTests.cs
new file mode 100644
index 00000000..366a3549
--- /dev/null
+++ b/Aetheris.CLI.Tests/RuledStepProbeHarnessTests.cs
@@ -0,0 +1,146 @@
+using System.Text.Json;
+using Aetheris.Kernel.Core.Step242;
+
+namespace Aetheris.CLI.Tests;
+
+public sealed class RuledStepProbeHarnessTests
+{
+ private static readonly string RepoRoot = FindRepoRoot();
+
+ [Fact]
+ public void Harness_Workflow_Generates_Deterministic_Wrapper_And_Reimports_Ruled_Probe()
+ {
+ var sourceProbe = Path.Combine(RepoRoot, "testdata", "step242", "generated", "ruled-a2", "ellipse-linear-extrusion-production.step");
+ Assert.True(File.Exists(sourceProbe), $"Expected ruled production probe at '{sourceProbe}'.");
+
+ var root = Path.Combine(Path.GetTempPath(), "aetheris-ruled-step-probe", Guid.NewGuid().ToString("N"));
+ var inputDir = Path.Combine(root, "input");
+ var wrapperDir = Path.Combine(root, "wrapper");
+ var outputDir = Path.Combine(root, "output");
+ Directory.CreateDirectory(inputDir);
+ Directory.CreateDirectory(wrapperDir);
+ Directory.CreateDirectory(outputDir);
+
+ const string probeName = "ellipseLinearExtrusionProduction";
+ var originalProbeName = Path.GetFileName(sourceProbe);
+ var rawProbeCopy = Path.Combine(inputDir, originalProbeName);
+ var canonicalInput = Path.Combine(inputDir, probeName + ".canonical-input.step");
+ var wrapperPath = Path.Combine(wrapperDir, probeName + ".firm");
+ var outputStepPath = Path.Combine(outputDir, probeName + ".canonical.step");
+
+ File.Copy(sourceProbe, rawProbeCopy, overwrite: true);
+
+ try
+ {
+ var canon = RunCli("canon", rawProbeCopy, "--out", canonicalInput, "--mode", "production", "--json");
+ Assert.Equal(0, canon.ExitCode);
+ Assert.True(File.Exists(canonicalInput));
+
+ var wrapper = BuildWrapperSource(probeName, Path.GetFileName(canonicalInput));
+ File.WriteAllText(wrapperPath, wrapper);
+
+ Assert.Equal(Path.Combine(wrapperDir, "ellipseLinearExtrusionProduction.firm"), wrapperPath);
+ Assert.Equal(Path.Combine(outputDir, "ellipseLinearExtrusionProduction.canonical.step"), outputStepPath);
+ Assert.Contains("InlineStep", wrapper, StringComparison.Ordinal);
+ Assert.Contains("../input/ellipseLinearExtrusionProduction.canonical-input.step", wrapper, StringComparison.Ordinal);
+
+ var build = RunCli("build", wrapperPath, "--out", outputStepPath, "--json");
+ Assert.Equal(0, build.ExitCode);
+ Assert.True(File.Exists(outputStepPath));
+
+ var stepText = File.ReadAllText(outputStepPath);
+ Assert.Contains("SURFACE_OF_LINEAR_EXTRUSION", stepText, StringComparison.Ordinal);
+ Assert.Contains("ELLIPSE", stepText, StringComparison.Ordinal);
+ Assert.DoesNotContain("B_SPLINE_SURFACE_WITH_KNOTS", stepText, StringComparison.Ordinal);
+
+ var import = Step242Importer.ImportBody(stepText);
+ Assert.True(import.IsSuccess, string.Join(Environment.NewLine, import.Diagnostics.Select(d => $"{d.Source}: {d.Message}")));
+ Assert.Contains(import.Value.Geometry.Surfaces, entry => entry.Value.Kind == Aetheris.Kernel.Core.Geometry.SurfaceGeometryKind.LinearExtrusion);
+
+ var reimportSmokePath = Path.Combine(outputDir, probeName + ".reimport-smoke.step");
+ var reimport = RunCli("canon", outputStepPath, "--out", reimportSmokePath, "--json");
+ Assert.Equal(0, reimport.ExitCode);
+ Assert.True(File.Exists(reimportSmokePath));
+
+ var analyze = RunCli("analyze", outputStepPath, "--json");
+ using var doc = JsonDocument.Parse(analyze.StdOut);
+ if (analyze.ExitCode == 0)
+ {
+ var summary = doc.RootElement.GetProperty("summary");
+ Assert.Equal(1, summary.GetProperty("bodyCount").GetInt32());
+ Assert.True(summary.GetProperty("faceCount").GetInt32() >= 1);
+ }
+ else
+ {
+ Assert.False(doc.RootElement.GetProperty("success").GetBoolean());
+ Assert.True(doc.RootElement.TryGetProperty("errorKind", out _));
+ }
+ }
+ finally
+ {
+ if (Directory.Exists(root))
+ {
+ Directory.Delete(root, recursive: true);
+ }
+ }
+ }
+
+ [Fact]
+ public void Harness_Documentation_And_Script_Are_Present_And_Reference_InlineStep()
+ {
+ var scriptPath = Path.Combine(RepoRoot, "tools", "Run-RuledStepProbe.ps1");
+ var docPath = Path.Combine(RepoRoot, "docs", "implementation", "ruled-tooling-a0-inline-step-probe-harness.md");
+ var ruledA2Path = Path.Combine(RepoRoot, "docs", "implementation", "ruled-a2-linear-extrusion-production-and-snapshot-refresh.md");
+
+ Assert.True(File.Exists(scriptPath), $"Expected ruled probe script at '{scriptPath}'.");
+ Assert.True(File.Exists(docPath), $"Expected ruled probe doc at '{docPath}'.");
+
+ var script = File.ReadAllText(scriptPath);
+ Assert.Contains("param(", script, StringComparison.Ordinal);
+ Assert.Contains("InlineStep", script, StringComparison.Ordinal);
+ Assert.Contains("probe-report.json", script, StringComparison.Ordinal);
+ Assert.Contains("Validate-Step-FreeCAD.ps1", script, StringComparison.Ordinal);
+
+ var doc = File.ReadAllText(docPath);
+ Assert.Contains("Run-RuledStepProbe.ps1", doc, StringComparison.Ordinal);
+ Assert.Contains("InlineStep", doc, StringComparison.Ordinal);
+ Assert.Contains("tooling only", doc, StringComparison.OrdinalIgnoreCase);
+ Assert.Contains("demo-output/ruled-probes/<probe-name>/", doc, StringComparison.Ordinal);
+
+ var ruledA2 = File.ReadAllText(ruledA2Path);
+ Assert.Contains("ruled-tooling-a0-inline-step-probe-harness.md", ruledA2, StringComparison.Ordinal);
+ }
+
+ private static string BuildWrapperSource(string identifier, string stagedFileName) =>
+ $@"model {identifier}ProbeHarness {{
+ units mm
+
+ solid {identifier}: InlineStep {{
+ path: ""../input/{stagedFileName}""
+ }}
+}}";
+
+ private static (int ExitCode, string StdOut, string StdErr) RunCli(params string[] args)
+ {
+ var stdout = new StringWriter();
+ var stderr = new StringWriter();
+ var exitCode = CliRunner.Run(args, stdout, stderr);
+ return (exitCode, stdout.ToString(), stderr.ToString());
+ }
+
+ private static string FindRepoRoot()
+ {
+ var directory = new DirectoryInfo(AppContext.BaseDirectory);
+ while (directory is not null)
+ {
+ if (File.Exists(Path.Combine(directory.FullName, "Aetheris.slnx")))
+ {
+ return directory.FullName;
+ }
+
+ directory = directory.Parent;
+ }
+
+ throw new InvalidOperationException("Unable to locate repository root for ruled probe tests.");
+ }
+}
diff --git a/docs/implementation/ruled-a2-linear-extrusion-production-and-snapshot-refresh.md b/docs/implementation/ruled-a2-linear-extrusion-production-and-snapshot-refresh.md
index 516e1600..13042269 100644
--- a/docs/implementation/ruled-a2-linear-extrusion-production-and-snapshot-refresh.md
+++ b/docs/implementation/ruled-a2-linear-extrusion-production-and-snapshot-refresh.md
@@ -37,6 +37,8 @@ FreeCAD validation remains optional and is not made mandatory for CI. In this en
.\tools\Validate-Step-FreeCAD.ps1 .\testdata\step242\generated\ruled-a2\ellipse-linear-extrusion-production.step
```
+For follow-on ruled/swept experimentation, RULED-TOOLING-A0 adds an InlineStep-based probe harness so developers can wrap a small probe asset instead of hand-authoring a full fixture; see `docs/implementation/ruled-tooling-a0-inline-step-probe-harness.md`.
+
## NIST snapshot refresh details
The RULED-A1 semantic change preserves exact swept-surface semantics during canonical STEP output. That can change byte-stable canonical hashes without changing import success, diagnostics status, or topology counts. The previously affected audit tests are the NIST per-file and aggregate audit snapshot checks in `Step242NistAuditHarnessTests`:
diff --git a/docs/implementation/ruled-tooling-a0-inline-step-probe-harness.md b/docs/implementation/ruled-tooling-a0-inline-step-probe-harness.md
new file mode 100644
index 00000000..3d970ec5
--- /dev/null
+++ b/docs/implementation/ruled-tooling-a0-inline-step-probe-harness.md
@@ -0,0 +1,147 @@
+# RULED-TOOLING-A0: InlineStep probe harness for ruled/swept STEP experiments
+
+## Why this exists
+
+RULED-A1 and RULED-A2 proved that Aetheris can preserve exact swept-surface semantics such as:
+
+- `SURFACE_OF_LINEAR_EXTRUSION`
+- `SURFACE_OF_REVOLUTION`
+- degree-1 `B_SPLINE_SURFACE_WITH_KNOTS` ruled classification
+
+That is enough geometry capability to keep iterating, but it is not enough tooling. Hand-authoring a full AP242 packet every time a developer wants to test one uncertain ruled or swept surface representation is too slow and too error-prone.
+
+RULED-TOOLING-A0 adds a lightweight harness around Firmament V2 `InlineStep` so the developer can focus on the small experimental STEP asset and let Aetheris handle canonical wrapping, real export, reimport, and evidence reporting.
+
+This milestone is tooling only. It does not add new ruled geometry capability, new Firmament ruled syntax, or new AIR ruled transitions.
+
+## Workflow
+
+The harness follows this path:
+
+```text
+small probe STEP
+ -> aetheris canon --mode production
+ -> generated Firmament V2 InlineStep wrapper
+ -> aetheris build
+ -> canonical AP242 output
+ -> aetheris analyze reimport
+ -> optional FreeCAD / SolidWorks inspection
+```
+
+The important distinction is that the wrapper is generated on demand. Codex does not need to hand-author a full `.firmfixture` just to test one uncertain surface token.
+
+## Entry point
+
+Use:
+
+```powershell
+.\tools\Run-RuledStepProbe.ps1 `
+ -Probe .\testdata\step242\generated\ruled-a2\ellipse-linear-extrusion-production.step `
+ -Name ellipseLinearExtrusionProduction
+```
+
+Optional examples:
+
+```powershell
+.\tools\Run-RuledStepProbe.ps1 `
+ -Probe .\testdata\step242\generated\ruled-a2\ellipse-linear-extrusion-production.step `
+ -Name ellipseLinearExtrusionProduction `
+ -Open
+
+.\tools\Run-RuledStepProbe.ps1 `
+ -Probe .\testdata\step242\probes\surface-of-revolution-line.step `
+ -Name surfaceOfRevolutionLine `
+ -Out .\demo-output\my-ruled-probes `
+ -FreeCAD `
+ -Keep
+```
+
+## Output layout
+
+The default output directory is:
+
+```text
+demo-output/ruled-probes/<probe-name>/
+```
+
+Each run writes:
+
+```text
+input/
+ <original probe filename>
+ <probe-name>.canonical-input.step
+
+wrapper/
+ <probe-name>.firm
+
+output/
+ <probe-name>.canonical.step
+ probe-report.json
+```
+
+`input/<original probe filename>` preserves the original authored probe filename in the harness output. `input/<probe-name>.canonical-input.step` is the staged canonical STEP that `InlineStep` actually wraps, because current Firmament InlineStep intentionally remains canonical-input-only.
+
+If `-Keep` is supplied, the harness also preserves command artifacts such as canon/build/analyze JSON and optional FreeCAD output for debugging.
+
+## Generated wrapper behavior
+
+The wrapper is intentionally tiny and uses the current Firmament V2 InlineStep syntax:
+
+```firmament
+model ellipseLinearExtrusionProductionProbeHarness {
+ units mm
+
+ solid ellipseLinearExtrusionProduction: InlineStep {
+ path: "../input/ellipseLinearExtrusionProduction.canonical-input.step"
+ }
+}
+```
+
+That means the experimental work stays inside the probe STEP asset. The wrapper is just a deterministic bridge into the real Aetheris pipeline.
+
+## What to inspect
+
+The harness prints a receipt and writes `probe-report.json` with:
+
+- the original probe path;
+- the copied probe path;
+- the staged canonical InlineStep input path;
+- the generated wrapper path;
+- the canonical AP242 output path;
+- reimport success;
+- best-effort analyze status and raw analyzer output when analyze is not currently supported for the emitted body;
+- entity evidence from token scans;
+- optional FreeCAD status.
+
+The token scan is intentionally simple and easy to read. It reports presence/count for:
+
+- `SURFACE_OF_LINEAR_EXTRUSION`
+- `SURFACE_OF_REVOLUTION`
+- `B_SPLINE_SURFACE_WITH_KNOTS`
+- `ELLIPSE`
+- `LINE`
+- `CIRCLE`
+- `CONICAL_SURFACE`
+- `CYLINDRICAL_SURFACE`
+
+This is not a replacement for importer validation; it is a quick receipt for the representation the exporter actually emitted.
+
+For this milestone, the authoritative reimport check is a second `aetheris canon` smoke pass on the emitted output, because that routes through `Step242Importer` and `Step242Exporter` again. `aetheris analyze` is still run as additional evidence, but some open ruled/swept bodies can currently fail there even when canonical reimport succeeds.
+
+## FreeCAD and SolidWorks workflow
+
+`-FreeCAD` is optional. When it is passed, the harness calls `tools/Validate-Step-FreeCAD.ps1` if present.
+
+- If `FreeCADCmd` is available on `PATH`, the harness validates the emitted canonical AP242 output and records the result.
+- If FreeCAD is unavailable, the harness reports a clear skip and still succeeds.
+
+SolidWorks remains a manual follow-up step outside CI. The intended path is to open `output/<probe-name>.canonical.step` from the harness output directory.
+
+## Limitations
+
+- Current Firmament `InlineStep` still requires Aetheris-canonical AP242 input, so the harness stages a canonical input STEP before wrapping.
+- The harness is intentionally single-probe and single-body oriented.
+- The token scan is textual evidence only; it does not claim semantic correctness by itself.
+- Some emitted open ruled/swept bodies currently reimport successfully but still fail `aetheris analyze`; the harness reports that separately instead of hiding it.
+- FreeCAD is optional and must not be required for normal CI.
+- This milestone does not add new ruled/swept geometry capability.
diff --git a/tools/Run-RuledStepProbe.ps1 b/tools/Run-RuledStepProbe.ps1
new file mode 100644
index 00000000..cea82ecc
--- /dev/null
+++ b/tools/Run-RuledStepProbe.ps1
@@ -0,0 +1,341 @@
+param(
+ [Parameter(Mandatory = $true)]
+ [string]$Probe,
+
+ [string]$Name,
+
+ [string]$Out,
+
+ [switch]$FreeCAD,
+
+ [switch]$Open,
+
+ [switch]$Keep
+)
+
+$ErrorActionPreference = 'Stop'
+
+function Get-RepoRoot {
+ $dir = Resolve-Path (Join-Path $PSScriptRoot '..')
+ while ($null -ne $dir) {
+ if (Test-Path -LiteralPath (Join-Path $dir.Path 'Aetheris.slnx')) {
+ return $dir.Path
+ }
+
+ $parent = Split-Path -Parent $dir.Path
+ if ([string]::IsNullOrWhiteSpace($parent) -or $parent -eq $dir.Path) {
+ break
+ }
+
+ $dir = Resolve-Path $parent
+ }
+
+ throw 'Unable to locate repository root from tools directory.'
+}
+
+function Get-SafeProbeName([string]$RawName) {
+ if ([string]::IsNullOrWhiteSpace($RawName)) {
+ return 'ruledProbe'
+ }
+
+ $safe = $RawName.Trim()
+ foreach ($invalid in [System.IO.Path]::GetInvalidFileNameChars()) {
+ $safe = $safe.Replace([string]$invalid, '-')
+ }
+
+ $safe = [System.Text.RegularExpressions.Regex]::Replace($safe, '\s+', '-')
+ $safe = $safe.Trim('.').Trim('-')
+ if ([string]::IsNullOrWhiteSpace($safe)) {
+ return 'ruledProbe'
+ }
+
+ return $safe
+}
+
+function Get-SafeIdentifier([string]$RawName) {
+ $identifier = [System.Text.RegularExpressions.Regex]::Replace($RawName, '[^A-Za-z0-9_]', '_')
+ if ([string]::IsNullOrWhiteSpace($identifier)) {
+ $identifier = 'probe'
+ }
+
+ if ($identifier[0] -match '[0-9]') {
+ $identifier = "probe_$identifier"
+ }
+
+ return $identifier
+}
+
+function Invoke-CliCommand {
+ param(
+ [Parameter(Mandatory = $true)]
+ [string[]]$Arguments
+ )
+
+ if (-not $script:CliReady) {
+ $buildOutput = & dotnet build 'Aetheris.CLI\Aetheris.CLI.csproj' -f net10.0 --nologo 2>&1 | ForEach-Object { $_.ToString() }
+ if ($LASTEXITCODE -ne 0) {
+ throw "Failed to build Aetheris.CLI before probe execution.$([Environment]::NewLine)$($buildOutput -join [Environment]::NewLine)"
+ }
+
+ $script:CliDllPath = Join-Path $script:RepoRoot 'Aetheris.CLI\bin\Debug\net10.0\aetheris.dll'
+ if (-not (Test-Path -LiteralPath $script:CliDllPath)) {
+ throw "Expected built CLI at '$script:CliDllPath' after dotnet build."
+ }
+
+ $script:CliReady = $true
+ }
+
+ $output = & dotnet $script:CliDllPath @Arguments 2>&1 | ForEach-Object { $_.ToString() }
+ return [pscustomobject]@{
+ ExitCode = $LASTEXITCODE
+ StdOut = ($output -join [Environment]::NewLine)
+ StdErr = ''
+ Arguments = $Arguments
+ }
+}
+
+function Get-EvidenceSummary([string]$StepText) {
+ $tokens = @(
+ 'SURFACE_OF_LINEAR_EXTRUSION',
+ 'SURFACE_OF_REVOLUTION',
+ 'B_SPLINE_SURFACE_WITH_KNOTS',
+ 'ELLIPSE',
+ 'LINE',
+ 'CIRCLE',
+ 'CONICAL_SURFACE',
+ 'CYLINDRICAL_SURFACE'
+ )
+
+ $result = [ordered]@{}
+ foreach ($token in $tokens) {
+ $count = ([regex]::Matches($StepText, [regex]::Escape($token))).Count
+ $result[$token] = [ordered]@{
+ present = ($count -gt 0)
+ count = $count
+ }
+ }
+
+ return $result
+}
+
+function Write-CommandArtifact {
+ param(
+ [Parameter(Mandatory = $true)]
+ [string]$BasePath,
+
+ [Parameter(Mandatory = $true)]
+ $Result
+ )
+
+ $artifact = [ordered]@{
+ exitCode = $Result.ExitCode
+ arguments = $Result.Arguments
+ stdout = $Result.StdOut
+ stderr = $Result.StdErr
+ } | ConvertTo-Json -Depth 6
+
+ Set-Content -LiteralPath $BasePath -Value $artifact -Encoding UTF8
+}
+
+$RepoRoot = Get-RepoRoot
+$resolvedProbe = (Resolve-Path -LiteralPath $Probe).Path
+
+if (-not (Test-Path -LiteralPath $resolvedProbe)) {
+ throw "Probe STEP file not found: $Probe"
+}
+
+$requestedName = if ([string]::IsNullOrWhiteSpace($Name)) { [System.IO.Path]::GetFileNameWithoutExtension($resolvedProbe) } else { $Name }
+$probeName = Get-SafeProbeName $requestedName
+$wrapperIdentifier = Get-SafeIdentifier $requestedName
+
+$rootOut = if ([string]::IsNullOrWhiteSpace($Out)) {
+ Join-Path $RepoRoot "demo-output\ruled-probes\$probeName"
+}
+else {
+ $candidate = if ([System.IO.Path]::IsPathRooted($Out)) { $Out } else { Join-Path $RepoRoot $Out }
+ [System.IO.Path]::GetFullPath($candidate)
+}
+
+$inputDir = Join-Path $rootOut 'input'
+$wrapperDir = Join-Path $rootOut 'wrapper'
+$outputDir = Join-Path $rootOut 'output'
+
+New-Item -ItemType Directory -Force -Path $inputDir, $wrapperDir, $outputDir | Out-Null
+
+$originalProbeName = [System.IO.Path]::GetFileName($resolvedProbe)
+$rawProbeCopyPath = Join-Path $inputDir $originalProbeName
+$canonicalInputPath = Join-Path $inputDir ($probeName + '.canonical-input.step')
+$wrapperPath = Join-Path $wrapperDir ($probeName + '.firm')
+$outputStepPath = Join-Path $outputDir ($probeName + '.canonical.step')
+$reimportSmokePath = Join-Path $outputDir ($probeName + '.reimport-smoke.step')
+$reportPath = Join-Path $outputDir 'probe-report.json'
+
+Copy-Item -LiteralPath $resolvedProbe -Destination $rawProbeCopyPath -Force
+
+$canonResult = Invoke-CliCommand -Arguments @('canon', $rawProbeCopyPath, '--out', $canonicalInputPath, '--mode', 'production', '--json')
+if ($Keep) {
+ Write-CommandArtifact -BasePath (Join-Path $outputDir 'canon-result.json') -Result $canonResult
+}
+
+if ($canonResult.ExitCode -ne 0) {
+ if (-not [string]::IsNullOrWhiteSpace($canonResult.StdErr)) {
+ Write-Error $canonResult.StdErr.Trim()
+ }
+
+ if (-not [string]::IsNullOrWhiteSpace($canonResult.StdOut)) {
+ Write-Host $canonResult.StdOut.Trim()
+ }
+
+ throw "Canonicalization failed for probe '$resolvedProbe'."
+}
+
+$wrapperRelativeInput = "../input/$([System.IO.Path]::GetFileName($canonicalInputPath))"
+ $wrapperText = @"
+model ${wrapperIdentifier}ProbeHarness {
+ units mm
+
+ solid ${wrapperIdentifier}: InlineStep {
+ path: "$wrapperRelativeInput"
+ }
+}
+"@
+
+Set-Content -LiteralPath $wrapperPath -Value $wrapperText -Encoding UTF8
+
+$buildResult = Invoke-CliCommand -Arguments @('build', $wrapperPath, '--out', $outputStepPath, '--json')
+if ($Keep) {
+ Write-CommandArtifact -BasePath (Join-Path $outputDir 'build-result.json') -Result $buildResult
+}
+
+if ($buildResult.ExitCode -ne 0) {
+ if (-not [string]::IsNullOrWhiteSpace($buildResult.StdErr)) {
+ Write-Error $buildResult.StdErr.Trim()
+ }
+
+ if (-not [string]::IsNullOrWhiteSpace($buildResult.StdOut)) {
+ Write-Host $buildResult.StdOut.Trim()
+ }
+
+ throw "Build failed for wrapper '$wrapperPath'."
+}
+
+$reimportResult = Invoke-CliCommand -Arguments @('canon', $outputStepPath, '--out', $reimportSmokePath, '--json')
+if ($Keep) {
+ Write-CommandArtifact -BasePath (Join-Path $outputDir 'reimport-result.json') -Result $reimportResult
+}
+
+$reimportSucceeded = ($reimportResult.ExitCode -eq 0)
+if (-not $Keep -and (Test-Path -LiteralPath $reimportSmokePath)) {
+ Remove-Item -LiteralPath $reimportSmokePath -Force -ErrorAction SilentlyContinue
+}
+
+$analyzeResult = Invoke-CliCommand -Arguments @('analyze', $outputStepPath, '--json')
+if ($Keep) {
+ Write-CommandArtifact -BasePath (Join-Path $outputDir 'analyze-result.json') -Result $analyzeResult
+}
+
+$analyzeSucceeded = ($analyzeResult.ExitCode -eq 0)
+$analyzeJson = $null
+if ($analyzeSucceeded -and -not [string]::IsNullOrWhiteSpace($analyzeResult.StdOut)) {
+ $analyzeJson = $analyzeResult.StdOut | ConvertFrom-Json
+}
+
+$outputStepText = Get-Content -LiteralPath $outputStepPath -Raw
+$evidence = Get-EvidenceSummary $outputStepText
+
+$freeCadStatus = [ordered]@{
+ attempted = [bool]$FreeCAD
+ available = $false
+ importSucceeded = $null
+ shapeValid = $null
+ skipped = $false
+ exitCode = $null
+ command = $null
+ output = $null
+}
+
+if ($FreeCAD) {
+ $validatorPath = Join-Path $RepoRoot 'tools\Validate-Step-FreeCAD.ps1'
+ if (Test-Path -LiteralPath $validatorPath) {
+ $freeCadCmd = Get-Command FreeCADCmd.exe, FreeCADCmd, freecadcmd -ErrorAction SilentlyContinue | Select-Object -First 1
+ if ($null -ne $freeCadCmd) {
+ $freeCadStatus.available = $true
+ $freeCadStatus.command = "$validatorPath $outputStepPath"
+
+ $freeCadOutput = & $validatorPath $outputStepPath 2>&1 | Out-String
+ $freeCadExitCode = $LASTEXITCODE
+ $freeCadStatus.exitCode = $freeCadExitCode
+ $freeCadStatus.output = $freeCadOutput.Trim()
+ $freeCadStatus.importSucceeded = ($freeCadExitCode -eq 0 -or $freeCadExitCode -eq 3)
+ $freeCadStatus.shapeValid = ($freeCadOutput -match 'shape_valid=true')
+
+ if ($Keep) {
+ Set-Content -LiteralPath (Join-Path $outputDir 'freecad-output.txt') -Value $freeCadOutput -Encoding UTF8
+ }
+ }
+ else {
+ $freeCadStatus.skipped = $true
+ $freeCadStatus.output = 'Skipped: FreeCADCmd was not found on PATH.'
+ }
+ }
+ else {
+ $freeCadStatus.skipped = $true
+ $freeCadStatus.output = 'Skipped: tools/Validate-Step-FreeCAD.ps1 is not present in this repository.'
+ }
+}
+
+$report = [ordered]@{
+ toolingOnly = $true
+ probe = $resolvedProbe
+ probeName = $probeName
+ rawProbeCopy = $rawProbeCopyPath
+ inlineStepInput = $canonicalInputPath
+ wrapper = $wrapperPath
+ outputStep = $outputStepPath
+ buildSucceeded = $true
+ reimportSucceeded = $reimportSucceeded
+ analyzeSucceeded = $analyzeSucceeded
+ analyzeSummary = if ($null -ne $analyzeJson) { $analyzeJson.summary } else { $null }
+ analyzeRaw = if ($analyzeSucceeded) { $null } else { $analyzeResult.StdOut }
+ surfaceEvidence = $evidence
+ freeCad = $freeCadStatus
+}
+
+$report | ConvertTo-Json -Depth 8 | Set-Content -LiteralPath $reportPath -Encoding UTF8
+
+Write-Host "Ruled STEP probe receipt"
+Write-Host " Input probe: $resolvedProbe"
+Write-Host " Input copy: $rawProbeCopyPath"
+Write-Host " InlineStep input: $canonicalInputPath"
+Write-Host " Generated wrapper: $wrapperPath"
+Write-Host " Canonical AP242 output: $outputStepPath"
+Write-Host " Reimport status: $(if ($reimportSucceeded) { 'succeeded' } else { 'failed' })"
+Write-Host " Analyze status: $(if ($analyzeSucceeded) { 'succeeded' } else { 'failed (best-effort only)' })"
+Write-Host " Report: $reportPath"
+Write-Host " Entity evidence:"
+
+foreach ($token in $evidence.Keys) {
+ $entry = $evidence[$token]
+ Write-Host " $token => present=$($entry.present) count=$($entry.count)"
+}
+
+if ($FreeCAD) {
+ if ($freeCadStatus.available) {
+ Write-Host " FreeCAD: exit=$($freeCadStatus.exitCode) shapeValid=$($freeCadStatus.shapeValid)"
+ }
+ else {
+ Write-Host " FreeCAD: skipped ($($freeCadStatus.output))"
+ }
+}
+
+if (-not $reimportSucceeded) {
+ if (-not [string]::IsNullOrWhiteSpace($reimportResult.StdOut)) {
+ Write-Host $reimportResult.StdOut.Trim()
+ }
+
+ throw "Reimport/analyze failed for '$outputStepPath'."
+}
+
+if ($Open) {
+ Start-Process $rootOut | Out-Null
+}