Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Firmament casing and layout proposal
Status: accepted convention; bounded formatter and guitar sweep implemented, 2026-10-01. The current contract is language style. The audit below records the pre-change behavior. This is not an exhaustive syntax migration: authored ports and template arguments require paired manual edits; unknown scopes and legacy spellings may remain. The guitar STEP, USD and display geometry are unchanged by the implemented sweep.
Keep the artifact vocabulary prominent, and let its descriptions read quietly. Firmament should still read as a specification of objects, scaffolding, and construction recipes. PascalCase on every property and reference currently makes all those different roles compete for attention.
Pre-change audit
language-style.mdprescribes PascalCase for both constructs and built-in fields. Authored names remain stylistically free.FirmamentV2Parsermixes case-sensitive canonical construct patterns with selected case-insensitive compatibility paths. Lowercasing a file is not a supported general conversion.AssemblyM0Parser,AssemblyFrameAuthoring, Concept point expansion, and Template/Feature binding also match specific spellings. For example,TranslateLocal,Over,On XY, and named Record members do not all share one spelling policy.- The actual V2 editor formatter is
FirmamentLanguageAnalysisService.Format. It preserves token text, changes spacing/layout, and reparses withFirmamentV2Parser. It does not currently perform semantic renaming or select all the assembly/project authoring paths. The olderFirmamentFormatterandFirmamentCanonicalFormatterbelong to the compatibility frontend and are not the V2 migration seam. - Generated semantic schemas already separate stable construct/field IDs from their displayed names. That is a useful existing seam for preferred spelling, completions, hover, and formatting; it is not yet a universal grammar registry.
- Symbol and published-port lookups use case-sensitive identities. Names also feed generated pattern identities, STEP product names, and provenance.
The current standalone functional pickup still validates through Aetheris.CLI. The proposed spellings have not been compiled. Existing source remains the compatibility baseline.
Recommended convention
| Semantic role | Convention | Examples |
|---|---|---|
| Artifact/declaration and construction kinds | PascalCase | Model, Assembly, Part, Concept Struct, Profile, Compose, Feature, WireRoute, FrameTransform |
| Reusable definition/type names | PascalCase | Humbucker, ControlKnob, PickupSpec, Length, Point2 |
| Concrete values, local geometry, occurrences, patterns, public ports | camelCase | standardPickup, layout, outline, neckPickup, poles, bottomSeat |
| Property labels and value parameters | camelCase | width, polePitch, from, translateLocal, minimumBendRadius, spec |
| Linking words and scope directives | lowercase | using, on, over, with, return, include, expose, bind |
| Scalar math functions and their parameters | camelCase | fretDistance(n, scale), pow(...) |
| Built-in variants, domain symbols, and external identities | Preserve domain spelling | Fixed, Revolute, Periodic, Stock, XY, +Z, mm, 304_Annealed |
This is a recommendation for authored style, not a rule that infers a symbol's
type from its capital letter. Definitions and occurrences are distinguished by
their declaration/binding context. A root product may retain its definition's
name, such as Assembly GuitarX0 and <Assembly GuitarX0>; nested occurrences
then read as body, neck, and electronics.
Keep Static, Template, Record, and Function as explicit declaration
kinds. Keep geometry and engineering forms such as Placement, Interface,
Mate, Linear, Series, Require, and Assert prominent too. An anonymous
Placement is still a domain construct; it does not become lowercase simply
because it has no authored name. expose and bind introduce publication and
input scopes rather than a new physical object.
Reusable Feature constructors remain PascalCase, e.g. Coil(...) -> Boss.
Their returned construction and named invocation results read as ordinary
values. Scalar Functions use camelCase, e.g. fretDistance(...) -> Length.
Both remain bounded compile-time evaluation; this adds no runtime execution,
Comptime keyword, inheritance, or general statement language.
Pickup: quieter fields, visible construction
Current excerpt:
Feature Coil(Center: Point2, Width: Length, Depth: Length,
Height: Length, Support: Plane) -> Boss {
RoundedRect2 Outline { Center: Center; Size: [Width,Depth]; Radius: 3mm }
Profile Section { Loop Outer { Outline |> TraceLoop } }
return Boss { On: Support; Profile: Section; Height: Height }
}
Proposed spelling and layout:
Feature Coil(center: Point2, width: Length, depth: Length,
height: Length, support: Plane) -> Boss {
RoundedRect2 outline {
center: center;
size: [width, depth];
radius: 3mm;
}
Profile section {
Loop outer { outline |> TraceLoop }
}
return Boss {
on: support;
profile: section;
height: height;
}
}
The same distinction helps the specification and its instances:
Record PickupSpec {
width: Length;
depth: Length;
polePitch: Length;
}
Static standardPickup: PickupSpec {
width: 88mm;
depth: 46mm;
polePitch: 10.2mm;
}
Static bridgePickupSpec = standardPickup with { polePitch: 10.4mm }
// Inside the full Humbucker recipe's Compose body:
Feature poleSeed = Pole(center: layout.firstPole, support: coilTop)
Linear Pattern poles {
source: poleSeed;
direction: layout.longitudinal.direction;
count: 6;
spacing: spec.polePitch;
}
These are excerpts, not standalone complete pickup definitions. width in the
Record is an authored member; size in RoundedRect2 is a compiler-owned field.
They look consistent but require different migration mechanisms.
Assembly: preserve the product tree
Subassembly ControlKnob {
<Assembly ControlKnob>
<Part skirt = Drum<R: 12mm, H: 3mm>>
material: Brass;
</Part>
<Part grip = Drum<R: 9mm, H: 9mm>>
material: AmberPolymer;
</Part>
</Assembly>
Interface<Fixed> coaxialStack {
datum: knobLayout.spindle;
members: [ControlKnob.skirt.spindleSeat, ControlKnob.grip.spindleSeat];
}
Mate gripOnSpindle: coaxialStack {
member: ControlKnob.grip.spindleSeat;
at: 3mm;
clocking: 0deg;
}
}
This excerpt assumes the referenced scaffolding and ports exist. The XML-like
containment still makes the assembly explicit. The lowercase properties explain
how its objects relate. Existing Drum parameter names R and H are preserved
here deliberately: replacing them with radius and height requires changing
the definition and its bound call sites, rather than formatting a use site.
Likewise, keep current published .Frame, .BottomSeat, and other authored
members until a definition-aware rename changes their declarations and every
reference. New definitions should prefer frame and bottomSeat. Intrinsic
point projections such as point.Position.X can gain preferred
point.position.x spelling only through their owning point binder; a formatter
must not lowercase arbitrary dotted references.
Layout rules
Use two-space indentation, preserving the current V2 convention. Give substantial objects and multi-field interfaces one field per line, and separate scaffolding, material construction, and publication with blank lines. Keep tiny single-field blocks compact where they remain legible. Keep closing XML tags on their own lines for multi-line occurrences.
Use spaces after commas and around assignments, arrows, and arithmetic. Keep
unit suffixes attached (0.1mm, 13deg) and dotted references uninterrupted.
Prefer descriptive new parameters to abbreviated L/W/H/R, with explicit
refactoring for existing definitions. Use a soft 100-column wrapping target;
never reorder profile spans, route events, section stations, keyed Sets, or
assembly children to satisfy layout.
Preserve semicolons required by the owning grammar. A formatter may standardize optional field terminators only in grammars that admit them; this is not a reason to redesign delimiters in the casing milestone. Preserve comments, quoted text, numeric literals, engineering units, and material/standard identifiers. In particular, do not round derived surface controls while formatting. The guitar's 0.1 mm authoring convention does not authorize changing exact geometry values.
Implementation boundary
- Compiler-owned spelling aliases. Give constructs, fields, and admitted
linking words preferred source spellings and explicit legacy aliases, with
stable semantic IDs unchanged. Resolve a field under its owning construct;
reject duplicate aliases such as
Fromplusfromin the same block. Keep user names and external identities case-sensitive. Do not make every regex case-insensitive or globally lowercase the source. - Safe formatting. Extend the existing V2 formatting service using bound token roles and source spans, not string replacement or BRep reconstruction. Apply preferred spelling only to positively identified compiler-owned tokens. Use the appropriate existing frontend/project context for admission before and after formatting. Preserve unknown/ambiguous tokens or leave that document unformatted with a specific diagnostic. No second grammar in the editor.
- Separate authored-name refactoring. Offer an explicit, previewable rename for Record fields, parameters, concrete geometry, ports, and occurrences. Include imported definitions and references; refuse incomplete project context and collisions. Ordinary Format Document must not change public identities, generated pattern keys, STEP product names, or exported provenance. A reviewed migration may intentionally change those names; compare geometry and report the identity changes rather than calling them byte-equivalent.
- Dogfood and qualify. First apply supported spelling/layout to the guitar's pickup, knob, and composition root. Qualify each newly admitted construct or frontend before advertising its spelling. Generate completions/help from the same authority and then update canonical documentation and fixtures. Keep accepted legacy source working during migration; do not repoint the current style guide at unsupported snippets.
Verification should check legacy/preferred semantic equivalence, unchanged geometry and transforms, unchanged identities for formatting alone, idempotence, comments/strings, alias collisions, and binding-sensitive renames. Include the guitar, profile editing, section chains, WireForm routes, and PMI release records, then run the repository's Release build, fast lane, and full serial gate.
The first bounded implementation should be preferred field labels and linking words plus layout, with authored-name migrations kept explicit. It should not rename the language's artifact constructs or redesign its authoring grammar.