Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
merge sync.
Yuechen Liee83d086f332
diff --cc docs/implementation/ruled-tooling-a0-inline-step-probe-harness.mdindex 3d970ec5,d1863467..9add0a37--- a/docs/implementation/ruled-tooling-a0-inline-step-probe-harness.md+++ b/docs/implementation/ruled-tooling-a0-inline-step-probe-harness.md@@@ -1,147 -1,15 +1,7 @@@- # RULED-TOOLING-A0: InlineStep probe harness for ruled/swept STEP experiments-# RULED-TOOLING-A0 Inline STEP probe harness- ## Why this exists-RULED-ANALYZE-A0 updated analyze/reporting so exact swept surface kinds are recognized in analyzer summaries. `SURFACE_OF_LINEAR_EXTRUSION` imports now appear as `linear-extrusion`, and `SURFACE_OF_REVOLUTION` imports now appear as `surface-of-revolution`.- RULED-A1 and RULED-A2 proved that Aetheris can preserve exact swept-surface semantics such as:-Open ruled/swept surface bodies still do not have exact volume integration. `aetheris analyze volume` reports that state as unsupported instead of throwing a dictionary-key exception; this milestone did not add ruled-surface area or volume integration.- - `SURFACE_OF_LINEAR_EXTRUSION`- - `SURFACE_OF_REVOLUTION`- - degree-1 `B_SPLINE_SURFACE_WITH_KNOTS` ruled classification-## Spatial probe follow-up- 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.-`aetheris analyze map` can now spatially inspect ruled and swept STEP artifacts as a ray/height-map probe. For example:- 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-```bash-aetheris analyze map testdata/step242/generated/ruled-a2/ellipse-linear-extrusion-production.step --plane xy --direction -z --resolution 8x8 --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.-Linear-extrusion faces are reported through the tessellated fallback path unless an exact intersection path is added later; the JSON diagnostics make that fallback explicit.diff --cc tools/Run-RuledStepProbe.ps1index cea82ecc,8f6bb253..ef9bec77--- a/tools/Run-RuledStepProbe.ps1+++ b/tools/Run-RuledStepProbe.ps1@@@ -1,341 -1,49 +1,19 @@@param(- [Parameter(Mandatory = $true)]- [string]$Probe,-- [string]$Name,-- [string]$Out,-- [switch]$FreeCAD,-- [switch]$Open,-- [switch]$Keep- [Parameter(Mandatory = $true)] [string] $Probe,- [Parameter(Mandatory = $true)] [string] $Name)$ErrorActionPreference = 'Stop'+ $repoRoot = Split-Path -Parent $PSScriptRoot+ $probePath = Resolve-Path -Path $Probe- 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- }-Write-Host "probe: $Name"-Write-Host "file: $probePath"- $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.'-$analyze = & dotnet run --project (Join-Path $repoRoot 'Aetheris.CLI') -- analyze $probePath --json 2>&1+ if ($LASTEXITCODE -ne 0) {- Write-Host "analyze: failed"- Write-Host $analyze- exit $LASTEXITCODE}- 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-$volume = & dotnet run --project (Join-Path $repoRoot 'Aetheris.CLI') -- analyze volume $probePath --json 2>&1-$volumeExit = $LASTEXITCODE-if ($volumeExit -eq 0) {- Write-Host "analyze: volume supported"- Write-Host $volume- exit 0}- 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-$message = ($volume | Out-String)-if ($message -match 'given key') {- Write-Host 'analyze: unexpected dictionary-key failure'- Write-Host $message- exit $volumeExit}- 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- }-if ($message -match 'Exact volume is not supported' -and $message -match 'linear-extrusion') {- Write-Host 'analyze: expected unsupported-volume nonzero for open linear-extrusion body'- Write-Host $message- exit 0}- 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-if ($message -match 'Exact volume is not supported' -or $message -match 'unsupported non-planar face') {- Write-Host 'analyze: expected unsupported-volume nonzero'- Write-Host $message- exit 0}- 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- }-Write-Host 'analyze: unexpected failure'-Write-Host $message-exit $volumeExit