Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add LLM CAD strategy notes

Yuechen Lif4d61548e49d
diff --git a/docs/llm-cad-strategy/00-purpose-and-scope.md b/docs/llm-cad-strategy/00-purpose-and-scope.md
new file mode 100644
index 00000000..4198d656
--- /dev/null
+++ b/docs/llm-cad-strategy/00-purpose-and-scope.md
@@ -0,0 +1,40 @@
+# 00 — Purpose and Scope
+
+LLMs need a CAD strategy manual because final geometry does not teach process. A BRep or STEP file can record faces, edges, loops, topology, and analytic surfaces, but it usually does not preserve the choices a competent CAD user made to build the part robustly.
+
+These notes help LLMs infer authoring intent, not merely list geometry.
+
+```text
+Geometry is what exists.
+Modeling strategy is how a competent CAD user would construct it robustly.
+Semantic decompilation tries to recover the second from the first.
+```
+
+## Primary uses
+
+These notes are especially aimed at:
+
+- Semantic decompilation from BRep, STEP, DisplayIR, screenshots, and inspection reports.
+- Firmament V2 candidate authoring.
+- Missing capability analysis for Firmament, AIR, CIR, BRep, DisplayIR, and related tools.
+- Plausible feature-tree recovery.
+- Separating geometric equivalence from resilient authoring strategy.
+
+## Scope
+
+The folder collects practical CAD modeling strategy adapted for LLMs. It focuses on how to reason about model construction order, stable references, feature decomposition, and design intent.
+
+These notes were started from observed CAD practice and Aetheris decompilation experiments. They are not a claim of novelty and are not a personal doctrine.
+
+## Non-goals
+
+These notes do not:
+
+- Define Firmament syntax by themselves.
+- Authorize parser changes.
+- Authorize lowering changes.
+- Change AIR, CIR, BRep, STEP import/export, DisplayIR, tessellation, or product behavior.
+- Replace implementation specifications or tests.
+- Claim that there is only one valid way to model a part.
+
+When these notes expose a missing capability, record the gap explicitly and propose a separate implementation milestone.
diff --git a/docs/llm-cad-strategy/01-geometry-inventory-vs-modeling-strategy.md b/docs/llm-cad-strategy/01-geometry-inventory-vs-modeling-strategy.md
new file mode 100644
index 00000000..8bece16c
--- /dev/null
+++ b/docs/llm-cad-strategy/01-geometry-inventory-vs-modeling-strategy.md
@@ -0,0 +1,54 @@
+# 01 — Geometry Inventory vs. Modeling Strategy
+
+Core lesson: do not confuse what faces and features are visible with how the model should be authored.
+
+A geometry inventory is useful evidence. It is not a feature tree.
+
+## Geometry inventory
+
+A BRep face inventory may report:
+
+- Planes.
+- Cylinders.
+- Cones.
+- Loops.
+- Holes.
+- Slots.
+- Adjacent faces and edge types.
+
+This tells the LLM what exists in the final shape. It does not prove which operation created each face.
+
+## Modeling strategy
+
+A modeling strategy describes a robust construction path, such as:
+
+- Start with a base mass.
+- Add or remove simple volumes.
+- Use semantic hole and slot features where available.
+- Pattern or mirror repeated features instead of duplicating them manually.
+- Finish edges last with fillets, chamfers, or rounds.
+
+The strategy should preserve design intent and stable references, not merely match the final shell.
+
+## Motivating example: CTC-01
+
+A naive interpretation of a prismatic part like CTC-01 might be:
+
+- “Extruded outline with holes.”
+
+That may match some visible geometry, but it can hide design intent and produce fragile source if the outline is doing too much.
+
+A more resilient interpretation to consider is:
+
+- “Block out the prismatic mass with boxes and cuts, then apply holes and slots, then finish edges.”
+
+This note does not claim the exact CTC-01 feature tree. The point is conceptual: final faces should be translated into a plausible authoring strategy before generating Firmament candidates.
+
+## LLM rule of thumb
+
+Before writing source, ask two questions:
+
+1. What geometry is visible?
+2. What construction order would make that geometry stable, editable, and CAD-native?
+
+If the answers differ, report both. Do not collapse strategy into inventory.
diff --git a/docs/llm-cad-strategy/02-prismatic-cad-first-principles.md b/docs/llm-cad-strategy/02-prismatic-cad-first-principles.md
new file mode 100644
index 00000000..e0ac453f
--- /dev/null
+++ b/docs/llm-cad-strategy/02-prismatic-cad-first-principles.md
@@ -0,0 +1,57 @@
+# 02 — Prismatic CAD First Principles
+
+Core lesson: for many CNC and prismatic mechanical objects, a useful first approximation is:
+
+```text
+Blocks + cuts + holes + edge finish.
+```
+
+This is not the only CAD method. It is a strong default hypothesis for many machined, fixture-like, bracket-like, and plate-like parts.
+
+## Start from simple masses
+
+Prefer simple, stable construction primitives early:
+
+- Boxes.
+- Bosses.
+- Pockets.
+- Slots.
+- Through-holes and blind holes.
+- Simple additive and subtractive volumes.
+
+Build the gross form before details. A clear blockout often gives later features better references and makes intent easier to inspect.
+
+## Prefer prismatic tools before arbitrary sketches
+
+When a block, cut, slot, or hole expresses the same intent as a complex profile, prefer the semantic feature. A simple 3D boolean over prismatic tools can often be treated like a constrained 2D boolean internally, without exposing arbitrary sketch complexity in source.
+
+This helps an LLM produce source that is closer to how a CAD user would maintain the model.
+
+## Why arbitrary sketch-first modeling is dangerous
+
+Sketch-first modeling can be powerful, but using it as the default escape hatch creates risk:
+
+- Self-intersection.
+- Ambiguous regions.
+- Loop closure problems.
+- Coincident geometry.
+- Constraint-solving complexity.
+- Fragile feature references.
+- Difficult LLM decompilation.
+
+A single heroic sketch may match the silhouette while destroying the recoverable authoring structure.
+
+## Admit sketches deliberately
+
+This does not ban sketches or profiles. It means they should be admitted deliberately when the part actually needs profile-level expressiveness.
+
+Good reasons to use sketches include:
+
+- A non-prismatic outline is genuinely central to the design.
+- A profile captures intent better than a set of boxes and cuts.
+- The language and kernel can represent the profile robustly.
+- The LLM can explain the references, dimensions, and ambiguity.
+
+## Edge finish comes late
+
+Fillets, chamfers, rounds, and other edge finishes usually belong near the end of the feature tree. They decorate or condition already-defined functional edges. Applying them too early can obscure the main shape spine and create fragile downstream references.
diff --git a/docs/llm-cad-strategy/03-semantic-decompilation-workflow.md b/docs/llm-cad-strategy/03-semantic-decompilation-workflow.md
new file mode 100644
index 00000000..dbaed59b
--- /dev/null
+++ b/docs/llm-cad-strategy/03-semantic-decompilation-workflow.md
@@ -0,0 +1,55 @@
+# 03 — Semantic Decompilation Workflow
+
+Semantic decompilation tries to recover a plausible authoring strategy from final geometry and inspection evidence. The output should separate facts, interpretation, confidence, and missing capabilities.
+
+## Practical workflow
+
+1. Establish the coordinate frame and bounding box.
+2. Identify the main mass or blockout.
+3. Identify major subtractive cuts.
+4. Identify secondary additive masses.
+5. Identify holes, slots, pockets, and repeated features.
+6. Identify symmetry, mirror, and pattern structure.
+7. Identify edge finishing.
+8. Produce a candidate feature tree in resilient order.
+9. Separate high-confidence, medium-confidence, and speculative features.
+10. Produce a missing capability matrix.
+
+## Shape spine vs. detail features
+
+Use a strong distinction between the shape spine and detail features.
+
+### Shape spine
+
+The shape spine is the minimum stable sequence needed to create the main body. It usually includes the base mass, major additions, and major removals that define the part’s silhouette and functional envelope.
+
+### Detail features
+
+Detail features refine the spine. They include holes, slots, pockets, repeated features, fillets, chamfers, rounds, and edge finishing.
+
+Do not let detail features obscure the main construction order. A model with many holes may still have a simple spine.
+
+## Expected report format
+
+Future decompilation reports should use this structure unless a task asks for a narrower format:
+
+```text
+- backend facts
+- visual/design interpretation
+- shape spine
+- candidate feature tree
+- feature decomposition table
+- missing capability matrix
+- confidence/ambiguity notes
+- recommended implementation milestones
+```
+
+## Confidence discipline
+
+Do not present every recovered feature as certain. Use confidence bands:
+
+- High confidence: directly supported by backend facts and visible design structure.
+- Medium confidence: plausible and useful, but not uniquely determined.
+- Speculative: a candidate strategy that needs more evidence or capability work.
+
+When two strategies create equivalent geometry, prefer the one that better preserves stable references and design intent, but record the ambiguity.
diff --git a/docs/llm-cad-strategy/99-glossary.md b/docs/llm-cad-strategy/99-glossary.md
new file mode 100644
index 00000000..0967d4e2
--- /dev/null
+++ b/docs/llm-cad-strategy/99-glossary.md
@@ -0,0 +1,101 @@
+# 99 — Glossary
+
+## BRep
+
+Boundary representation: a model of solid geometry using faces, edges, vertices, loops, surfaces, and topology.
+
+## STEP/AP242
+
+A STEP data exchange format profile used to carry CAD product geometry and related model data between systems.
+
+## Firmament
+
+Aetheris source language for describing CAD models and related design intent at a higher level than raw kernel geometry.
+
+## AIR
+
+Aetheris Intermediate Representation: an internal representation used between source-level authoring and lower-level geometry or kernel operations.
+
+## CIR
+
+Constructive Intermediate Representation: an intermediate layer for constructive geometry intent and operations.
+
+## DisplayIR
+
+A representation used for display-oriented inspection and visualization data.
+
+## Feature tree
+
+An ordered sequence of modeling operations that constructs a part from stable references and earlier features.
+
+## Modeling strategy
+
+The CAD-native construction plan for a part: what to build first, what to cut later, what references to preserve, and what details to defer.
+
+## Semantic decompilation
+
+Recovering a plausible modeling strategy, feature tree, and design intent from final geometry and inspection evidence.
+
+## Prismatic object
+
+A mostly block-like, machined, extruded, or planar-faced object where boxes, cuts, pockets, holes, and slots explain much of the shape.
+
+## Blockout
+
+The early gross mass of a model before fine details and edge finishing are applied.
+
+## Boss
+
+An added protruding mass, often used as a pad, raised feature, or mounting region.
+
+## Cut
+
+A subtractive operation that removes material from an existing body.
+
+## Pocket
+
+A recessed cut that removes material without necessarily passing through the entire part.
+
+## Slot
+
+An elongated cut or opening, often with straight sides and rounded or rectangular ends.
+
+## Through-hole
+
+A hole that passes completely through the body.
+
+## Clearance hole
+
+A hole sized to allow a fastener or shaft to pass through without threading into that part.
+
+## Fillet
+
+A rounded transition applied to an edge or corner.
+
+## Chamfer
+
+A beveled transition applied to an edge or corner.
+
+## Round
+
+A general rounded edge treatment; often used interchangeably with fillet in casual CAD discussion.
+
+## Edge finish
+
+Late-stage edge treatments such as fillets, chamfers, and rounds.
+
+## Sketch/profile
+
+A 2D curve, loop, or region used as input to an operation such as extrude, cut, revolve, or sweep.
+
+## Resilient modeling
+
+Modeling that remains understandable and editable because it uses stable references, clear feature order, and intent-preserving operations.
+
+## Geometric equivalence
+
+Two models are geometrically equivalent when their final shapes match, even if they were authored through different feature trees.
+
+## Design intent
+
+The functional and editable meaning behind the geometry: why features exist, which dimensions matter, and how the model should change safely.
diff --git a/docs/llm-cad-strategy/README.md b/docs/llm-cad-strategy/README.md
new file mode 100644
index 00000000..7f942a1b
--- /dev/null
+++ b/docs/llm-cad-strategy/README.md
@@ -0,0 +1,65 @@
+# LLM CAD Strategy Notes
+
+These notes collect practical CAD strategy in a form LLMs can use. They are not a claim of novelty. They are a translation layer between experienced CAD modeling habits and LLM reasoning for Aetheris, Firmament, AIR, and semantic decompilation work.
+
+## What this folder is
+
+This folder is a living internal wiki for CAD-native reasoning. It gives LLMs and human reviewers a shared vocabulary for thinking about robust CAD authoring strategy, not just final geometry.
+
+The intended audience is:
+
+- Codex, ChatGPT, Claude, and other LLMs working on Aetheris tasks.
+- Humans supervising Firmament, AIR, decompilation, and kernel development.
+- Future maintainers who need to distinguish a plausible feature strategy from a raw face inventory.
+
+## What this folder is not
+
+This folder is not:
+
+- A language specification.
+- A parser or lowering implementation plan by itself.
+- A replacement for Firmament, AIR, BRep, DisplayIR, STEP, or kernel documentation.
+- A claim that these modeling habits were invented here.
+- A rule that every CAD model must be built the same way.
+
+The notes describe practical CAD modeling strategy and resilient modeling strategy as working heuristics for LLMs.
+
+## How LLMs should use these notes
+
+Use these notes when you need to:
+
+- Infer authoring intent from BRep, STEP, DisplayIR, screenshots, or CLI evidence.
+- Propose a resilient feature tree rather than merely listing visible faces.
+- Generate Firmament V2 candidates in a robust construction order.
+- Identify missing Firmament, AIR, kernel, or display capabilities.
+- Explain ambiguity and confidence instead of pretending that one feature tree is certain.
+
+Treat the notes as guidance for reasoning. Do not treat them as permission to change product behavior.
+
+## Current lesson list
+
+- [00 — Purpose and scope](00-purpose-and-scope.md)
+- [01 — Geometry inventory vs. modeling strategy](01-geometry-inventory-vs-modeling-strategy.md)
+- [02 — Prismatic CAD first principles](02-prismatic-cad-first-principles.md)
+- [03 — Semantic decompilation workflow](03-semantic-decompilation-workflow.md)
+- [99 — Glossary](99-glossary.md)
+
+## How to add future lessons
+
+Future lessons should be short, concrete, and field-manual style. Prefer examples that help an LLM choose between competing authoring strategies.
+
+A new lesson should usually include:
+
+- The core lesson in one or two sentences.
+- A practical CAD pattern.
+- The LLM failure mode it prevents.
+- The evidence an LLM should look for.
+- Boundaries: what the lesson does not imply.
+
+Keep personal branding out of the folder. Attribute lessons to observed CAD practice, Aetheris experiments, and reusable modeling experience.
+
+## Boundary with implementation docs
+
+Implementation docs define syntax, lowering, AIR contracts, BRep behavior, STEP import/export, DisplayIR, tests, and product behavior. This folder informs how LLMs reason about those systems, but it does not change them.
+
+If a note suggests that Aetheris needs a new capability, record that as a missing capability or future milestone. Do not silently treat the note as an implementation authorization.