Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Historical JSON-shaped .firmasm model (legacy syntax)
This document records the deprecated JSON-shaped .firmasm syntax. The .firmasm extension itself is current: it is the Firmament V2 Assembly document profile described in Assembly M2. The historical details below remain only to explain legacy fixtures, migration, and compatibility commands.
1) Core philosophy
- STEP/AP242 is a foreign interchange format.
- JSON-shaped
.firmasmwas Aetheris's authoritative v0 representation and is now legacy compatibility input. - Aetheris does not adopt or normalize away STEP assembly ambiguity as native semantics.
- Assembly behavior is defined by Aetheris contracts (
.firmasm, executor, bounded exporter), not by importer guesswork.
2) STEP classification rule (ASM-A2.75)
Aetheris classifies STEP input by rigid root count (MANIFOLD_SOLID_BREP roots):
- exactly 1 rigid root => part-like STEP
- more than 1 rigid root => assembly-like STEP
Consequences:
- Multi-root STEP is never treated as a native multi-body part in Aetheris.
- Multi-root STEP is always assembly-like input and must go through the assembly extraction/import path.
- Single-part exact BRep import path accepts one rigid root only.
3) Assembly pipeline (full flow)
STEP assembly
↓
classification (part-like / assembly-like)
↓
assembly extraction
↓
.firmasm + canonical STEP parts
↓
execution (ASM-A3)
↓
world-space multi-body composition
↓
bounded roundtrip export (ASM-A4)
Stage semantics:
Classification
- Detects part-like vs assembly-like STEP by rigid root count.
- Guarantees deterministic routing decision.
- Does not attempt to reinterpret multi-root STEP as a single native part.
Assembly extraction
- Produces flat
.firmasminstances plus deduplicated part STEP files. - Uses composed rigid transforms for each emitted instance.
- Does not create mates, motion, or solver constraints.
- Produces flat
.firmasm+ canonical STEP parts.firmasmcaptures authoritative assembly semantics.- STEP files are foreign part payloads validated at load time through bounded import.
Execution (ASM-A3)
- Executes
.firmasminstances as rigid placements of real imported geometry. - Emits one composed multi-body BRep containing all instance bodies.
- Executes
Bounded roundtrip export (ASM-A4)
- Exports one STEP file per executed instance.
- Writes
roundtrip.package.jsonas outbound package metadata. - Does not emit a true AP242 assembly file in v0.
4) .firmasm contract (ASM-A0)
Historical .firmasm v0 syntax was JSON by design. Current .firmasm is Firmament V2 source.
Why JSON:
- machine IR first
- deterministic serialization behavior
- strict schema-like validation with explicit unknown-field rejection
Top-level required sections:
manifest(object)version(string, required)
assembly(object)name(string, required)units(string, required)
parts(object, non-empty)- each part value requires:
kind:firmamentorstepsource: relative/absolute path string
- each part value requires:
instances(array, non-empty)- each instance requires:
id: unique stringpart: existing key inpartstransformobject with:translate:[x, y, z]numeric array of length 3 (required)rotate_deg_xyz:[rx, ry, rz]numeric array of length 3 (optional)
- each instance requires:
Validation rules (non-exhaustive but contract-critical):
.firmasmfile extension is required for manifest files.- Top-level manifest must be a JSON object.
- Unknown top-level fields are rejected.
- Unknown fields in part, instance, and transform objects are rejected.
partsandinstancesmust both be present and non-empty.- Instance ids must be unique.
- Every instance must reference an existing part.
- STEP part files must exist and pass bounded importer acceptance.
- Part kind outside
firmament|stepis rejected.
Current execution scope note:
- Contract allows
firmamentandsteppart kinds. - ASM-A3 executor currently executes only loaded STEP parts;
firmamentparts are loadable but not executable yet.
5) Execution model (ASM-A3)
Execution model is flat and rigid:
- No hierarchy execution tree in v0.
- Instances are executed from a flat list.
- Rigid transforms only.
- Geometry is real imported BRep geometry, not proxy meshes.
- Output is one composed multi-body BRep with deterministic ID remapping.
Transform order is fixed:
- rotate around X
- rotate around Y
- rotate around Z
- translate
No mates/constraints/motion solving occurs during execution.
6) Roundtrip export model (ASM-A4)
Outbound export shape is intentionally bounded:
- one STEP file per executed instance
- one package manifest:
roundtrip.package.json
roundtrip.package.json carries:
schema:asm-a4-step-instance-package/v1nativeAuthority:.firmasmexportIntent:outbound-step-interop- source assembly metadata and per-instance STEP file records
Why true STEP assembly export is not used yet:
- v0 freezes a truthful interop boundary without pretending full AP242 assembly authoring support.
- Per-instance package avoids lossy/ambiguous mapping while preserving executed geometry output.
Authority rule after export:
.firmasmremains authoritative even after roundtrip export.- Exported STEP artifacts are outbound interop deliverables, not native authority.
7) CLI surface (source of truth)
These commands are part of the current assembly-adjacent workflow:
aetheris analyze <file.step> [--face|--edge|--vertex] [--json]- Imports a part-like STEP body and reports topology/geometry summary.
- For assembly-like STEP, JSON mode returns structured failure (
errorKind: assembly-like-step) with route hint. - Use for part-like inspection and classifier-visible failure routing.
aetheris analyze map <file.step> ... --json- Computes orthographic depth/thickness maps for imported STEP bodies.
- Use when view-based sampling of a part-like body is needed.
aetheris analyze section <file.step> ... --json- Computes principal-plane section loops for imported STEP bodies.
- Use when deterministic cross-section diagnostics are needed.
aetheris canon <file.step> --out <canonical.step> [--json]- Imports a part-like STEP body and re-exports canonical AP242.
- Use for bounded canonicalization of supported single-root input.
aetheris asm exec <file.firmasm> [--json]- Loads
.firmasm, executes rigid instance placements, and composes multi-body result. - JSON output includes assembly counts and analyzer summary on composed body.
- Loads
aetheris asm export <file.firmasm> --out <directory> [--json]- Executes
.firmasmthen writes per-instance STEP files +roundtrip.package.json. - Use for bounded outbound STEP interop packages.
- Executes
8) Invariants (non-negotiable)
- Typed Firmament Assembly source and normalized AssemblyIR are authoritative;
.firmasmis legacy transform-first input. - STEP assembly is not native authority in Aetheris.
- Multi-root STEP is assembly-like input, never native multi-body part.
- Execution in v0 is flat + rigid only.
- No silent healing beyond bounded seams (strict parse/import/validation failures are surfaced).
- Roundtrip export does not transfer authority away from
.firmasm.
9) Non-goals (v0)
- mates/constraints solving
- kinematic motion
- hierarchy-preserving assembly execution
- native multi-body part semantics from multi-root STEP
- full AP242 assembly export
- feature reconstruction from STEP assemblies
10) Known limitations
- ASM-A3 executor currently executes STEP parts only;
firmamentparts are not yet executable in assembly runtime. - Roundtrip exporter emits per-instance STEP package, not true AP242 assembly structure.
- Exported instance STEP files are expected single-body instance payloads.
- Part-like importer rejects assembly-like multi-root exact-BRep input and requires extraction/import routing.
- Some STEP importer subsets remain bounded by existing STEP/AP242 support matrix and emit explicit unsupported diagnostics.
11) Future directions (bounded)
- true AP242 assembly export
- hierarchy-aware execution mode
- mates/constraints layer on top of rigid instances
- richer native part reconstruction pipelines