Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Contributing to Aetheris
Thank you for improving Aetheris. Keep changes focused, explain the engineering intent, and preserve the rule that supported semantics are emitted truthfully while unsupported semantics fail with actionable diagnostics.
Release scope
The 2.0.0 release pass covers release hygiene, documentation, tests and narrowly scoped correctness fixes. Develop new capabilities on an explicitly agreed branch and keep experimental API status visible.
Build and test
Install the .NET SDK selected by global.json.
Source builds that include Drawing Notes also require Node 24 and npm. MSBuild
restores the pinned PDF.js dependency from Aetheris.Drawing/Web/package-lock.json
with install scripts and optional native packages disabled. Only selected browser
runtime assets and licenses are embedded; downloaded distributions stay ignored.
Published Aetheris tools do not require Node or npm. See
Aetheris.Drawing/Web/README.md.
Firmament pins Copeland's published managed VTS/WGSL compiler family to 0.1.0.
A fresh checkout restores it from NuGet.org without a Copeland checkout or local
feed. The CI action .github/actions/prepare-managed-wgsl verifies this public
restore. Use the canonical solution:
dotnet restore Aetheris.slnx
dotnet build Aetheris.slnx -c Release -m:1
dotnet test Aetheris.slnx -c Release --no-build -m:1 -- RunConfiguration.MaxCpuCount=1
Two test lanes
The command above is the full corpus lane and is what has to be green before you commit. It imports the whole NIST and OCCT corpus, so it is the lane that actually protects the interchange behaviour.
For the edit-run-edit inner loop there is a fast lane that skips the corpus-driven tests:
dotnet test Aetheris.Kernel.Core.Tests -c Release --no-build --filter "Category!=SlowCorpus"
Use the fast lane while iterating; never use it as the gate. Its test count and runtime vary with the source and available corpus witnesses.
A test belongs in [Trait("Category", "SlowCorpus")] when its cost is dominated by importing a
large corpus file rather than by the behaviour it is checking. Keep at least one cheap test per
behaviour outside the trait, so the fast lane still fails when something is broken rather than
merely running fewer tests. Aetheris.Kernel.Firmament.Tests has the trait too, but its time is
spread evenly across real geometry work rather than concentrated in corpus I/O, so the split
buys much less there.
The NIST audit keeps strict canonical STEP byte snapshots. Three recovered-pcurve specimens
have qualified Linux hashes in testdata/step242/manifests/nist.v0.canonical-linux.json:
native math changes tiny UV values and exact geometry sharing changes entity numbering.
The companion overrides only their expected hash on Linux; status, diagnostics, file size
and topology counts still use the common snapshot. When refreshing these specimens,
qualify both Windows and Linux exports and refresh the companion explicitly. All other
specimens retain the common byte hash on both platforms.
Importing corpus files in tests
Do not call File.ReadAllText + Step242Importer.ImportBody directly in a test. Use the shared
memoized fixture:
var body = Step242Corpus.Body("testdata/step242/nist/CTC/nist_ctc_02_asme1_ap242-e2.stp");
var import = Step242Corpus.Import(relativePath); // when the diagnostics matter
var text = Step242Corpus.Text(relativePath); // when the file text itself matters
The corpus has 48 distinct files and the test project reads from it at roughly two hundred call
sites. Importing every file exactly once costs about ten seconds; doing it per call site cost
about ninety-eight. Parsing is under a second of that, so caching the parsed document would buy
almost nothing - the body is what is expensive to build, so the body is what is cached. A
BrepBody is read-only once constructed, which is what makes sharing it safe.
Two cases must still import for themselves and should take only Step242Corpus.Text: tests that
install a Step242Importer.CaptureLoopRole*Diagnostics scope, because it collects while the
import runs, and tests under Step242Importer.PreserveRationalSurfaces(), because it changes
what the import produces.
Cadmata and the VS Code extension use TSPack and their checked-in lock files:
The release workflow pins TSPack source 01051b791cf83757a1c419ef7bc276d9de787a9d
(npm peers, scoped tools, local dependencies and explicit runtime providers). Build the local Telos
producer before syncing Cadmata; its exported dist files are ignored.
./scripts/Build-CadmataFrontend.ps1 runs the complete frontend producer and
qualification below. CI runs it before the long .NET lane and again when staging.
Use separate generated dependency directories for each package; remove obsolete
client-to-workspace node_modules junctions before regenerating with sync --force.
Push-Location Aetheris.Web.Runtime/telos
npm ci --ignore-scripts
npm run build
Pop-Location
Push-Location aetheris.client
tspack sync --root ..
tspack check --root ..
tspack run typecheck --root ..
tspack run test --root ..
tspack run build --root ..
tspack run lint --root ..
Pop-Location
Push-Location tools/vscode-firmament
tspack sync
tspack check
tspack run typecheck
tspack run test
tspack run build
Pop-Location
Use Aetheris.CLI as the ground-truth inspection surface while developing:
dotnet run --project Aetheris.CLI -c Release -- --help
dotnet run --project Aetheris.CLI -c Release -- analyze path/to/part.step --json
The shell entry points under scripts/ remain useful for targeted Linux/framework automation. The release qualification commands above are the authoritative Windows path for 2.0.0.
Contribution expectations
- Keep pull requests small enough to review and test as one engineering claim.
- Add tests for behavior changes and run the affected real CLI, package, or UI path.
- Use
ToleranceContextandToleranceMath; do not introduce ad hoc geometry epsilon constants. - State whether display work changes STEP semantics, BRep topology, Firmament/AIR/CIR lowering, DisplayIR authority, or frontend presentation only.
- Update public documentation whenever a user-visible command, boundary, diagnostic, or example changes.
- Put current user-facing behavior only under
docs/public. Architecture, experiments, and development evidence belong underdocs/developmentand must not silently become the public contract.
Repository content map
| Location | Durable purpose |
|---|---|
docs/public/ |
Authoritative current user documentation. |
docs/development/ |
Historical engineering, architecture, milestones, experiments, and evidence. |
docs/release/ |
Release qualification, staging, claims, and contracts. |
docs/legal/ |
Legal-review candidates and counsel questions. |
fixtures/ |
All Firmament-family test source and corpus metadata, including .firmament, .firmfixture, and .firmasm. |
testdata/ |
Non-Firmament external/reference inputs and deliberate golden exports. |
samples/ |
External consumer integration examples. |
demos/ |
Runnable narrative demonstrations of Aetheris capabilities. |
test-support/ |
Auxiliary projects and assets used by tests. |
artifacts/local/ |
Generated local output; ignored by Git. |
Before adding content, use an existing location above. Do not create another top-level documentation, fixture, example, or generated-output bucket without an explicit architectural reason. Generated output is governed by the generated-artifact policy: tools default to artifacts/local/, and only bounded, reviewed evidence or goldens may be promoted into source control. Run ./scripts/Test-RepositoryLayout.ps1 before submitting structural changes.
Rights and provenance
Submit only code, documentation, models, and assets that you have the right to contribute. Record third-party source, author, license, and redistribution constraints in the pull request and, when bundled, in THIRD_PARTY_NOTICES.md. Tool-assisted or AI-assisted work is acceptable, but the contributor remains responsible for the right to submit it and for reviewing its correctness and provenance.
Contributor license agreement status
Aetheris intends to use a contributor-friendly CLA: contributors keep copyright, while granting the project owner enough non-exclusive rights to distribute contributions under AGPL-3.0 and alternative licenses. In return, the intended bargain commits Aetheris to continuing AGPL availability rather than using the CLA to make the community version proprietary-only.
The current CLA-CANDIDATE.md is draft preparation for human attorney review. It is not a final legal agreement and this repository does not yet define click-through, pull-request, or signature acceptance. Until counsel and the project owner publish approved terms and acceptance mechanics, maintainers should not represent a contribution as having accepted that draft.
Legal reviewers should also see the CLA counsel checklist.