Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
docs(firmament): complete DOC4 semantic gap closure for LLM authors
Yuechen Li7b5b0f730701
diff --git a/references/firmament/01-language-overview-and-pipeline.md b/references/firmament/01-language-overview-and-pipeline.mdindex 61a453c7..a5048a11 100644--- a/references/firmament/01-language-overview-and-pipeline.md+++ b/references/firmament/01-language-overview-and-pipeline.md@@ -32,7 +32,7 @@ Compile flow today:9. Run CNC DFM checks (narrow current rule).10. Lower primitives/booleans.11. Execute primitives then booleans.-12. Enclosed-void schema guard.+12. Enclosed-void schema guard (hard failure when disallowed by process policy).13. Run validation ops against executed geometry.The returned artifact includes parsed doc, compiled schema, lowered plan, primitive/boolean execution result, and validation execution result.@@ -48,3 +48,10 @@ The returned artifact includes parsed doc, compiled schema, lowered plan, primitExport chooses the **last successfully executed geometric body by op index** (primitive or boolean).Validation ops are never export bodies.++Validation-op failures are diagnostic-only: they can mark validations unsuccessful and add warning diagnostics, but they do not by themselves block compile success or STEP export.++## Reference scope note (authoring vs integration API)++This corpus is primarily for `.firmament` file authoring semantics.+If you are integrating at compiler API level, inspect implementation contracts directly (`FirmamentCompileResult` + `FirmamentCompilationArtifact`) and the integration tests in `Aetheris.Kernel.Firmament.Tests`.diff --git a/references/firmament/02-file-shape-and-sections.md b/references/firmament/02-file-shape-and-sections.mdindex 22888c56..ef786601 100644--- a/references/firmament/02-file-shape-and-sections.md+++ b/references/firmament/02-file-shape-and-sections.md@@ -34,6 +34,9 @@ Current implementation note: units must be present but are not currently validat- Each entry begins with `-` and contains an object-like block including `op`.- `op` token must map to known op kind.+`ops[n]` count behavior (important): parser accepts the bracketed integer format but uses the actual list entries that follow.+The declared `n` is informational/canonical style only; it is not enforced as a hard count check.+## Known op kinds (current)Primitive:@@ -72,7 +75,9 @@ When `schema` is present:Additional current behavior:- CNC DFM currently checks subtract-tool cylinder `with.radius >= minimum_tool_radius`.-- Enclosed voids are rejected for non-additive process modes.+- Enclosed voids are a hard compile failure for non-additive process modes (including default/no-schema behavior, `cnc`, and `injection_molded`).+ - Practical trip case: a sealed cavity (for example, subtracting a fully enclosed sphere cavity) fails compile under those modes.+ - `additive` explicitly allows enclosed voids.## PMI behavior (current)diff --git a/references/firmament/03-primitives-and-local-frames.md b/references/firmament/03-primitives-and-local-frames.mdindex aa8f879d..92b0f3bf 100644--- a/references/firmament/03-primitives-and-local-frames.md+++ b/references/firmament/03-primitives-and-local-frames.md@@ -191,3 +191,7 @@ These are compile-time contracts used by placement and validation target checks.Boolean result ports are intentionally box-like, not primitive-tool-like.⚠️ Boolean result ports are heuristic selectors, not guaranteed topological truths. `top_face`/`bottom_face` use orientation filters (for example, planar normal Z thresholds), so rotated or complex geometry can produce empty or surprising matches.++⚠️ **Pointed cone selector trap:** cone ports are compile-time allowed, but runtime selector resolution is topology-truthful.+For a pointed cone with `top_radius: 0`, there is no top planar cap, so `cone.top_face` resolves to zero elements (effectively unavailable).+Likewise, for `bottom_radius: 0`, `cone.bottom_face` resolves to zero.diff --git a/references/firmament/05-booleans-safe-families-patterns.md b/references/firmament/05-booleans-safe-families-patterns.mdindex 5c3eaaf4..1c3a0cfe 100644--- a/references/firmament/05-booleans-safe-families-patterns.md+++ b/references/firmament/05-booleans-safe-families-patterns.md@@ -76,7 +76,7 @@ Current continuation family is intentionally narrow:- follow-on tool kind must be `cylinder` or `cone`- geometric guards enforce non-overlap/non-tangent/non-degenerate-safe constraints-`intersect` does execute, but it is outside safe-family continuation semantics (`WasValidated=false` path) and should be treated as a narrow subset operation rather than a safe-chain building block.+`intersect` computes the geometric overlap of `left` and `with`. It does execute, but is outside safe-family continuation semantics (`WasValidated=false` path) and only succeeds inside the currently recognized bounded subset; treat it as a narrow subset operation rather than a safe-chain building block.Anything outside this family should be treated as deferred/unsupported unless explicitly test-backed.@@ -154,6 +154,12 @@ Worked angle example:- pattern `angle_step_degrees = 45`, `count=3`- generated angles: `cir1=75`, `cir2=120`, `cir3=165`+Span-vs-step comparison (same `count=4`, source/base angle = `0`):+- `angle_degrees: 360` (span form) ⇒ angular step is `360/4 = 90` ⇒ generated angles: `90, 180, 270, 360`+- `angle_step_degrees: 90` (step form) ⇒ explicit per-instance step `90` ⇒ generated angles: `90, 180, 270, 360`++Use span form when you want to describe a total covered arc; use step form when you want explicit per-instance spacing regardless of count.+Also chains primary boolean reference sequentially like linear pattern.---diff --git a/references/firmament/06-supported-vs-deferred.md b/references/firmament/06-supported-vs-deferred.mdindex 70eb9fed..75653d11 100644--- a/references/firmament/06-supported-vs-deferred.md+++ b/references/firmament/06-supported-vs-deferred.md@@ -52,12 +52,18 @@ Execution semantics:- `count: 0` currently means "expect selector resolves to no elements" and passes only when resolved count is zero.- failures add warning diagnostics; they do not stop primitive/boolean execution.- `expect_manifold`: bare feature-id only (selector target not supported at execution).+ - this is a topology/geometry check, not syntax checking.+ - operationally, current checker verifies 2-manifold-style edge incidence: every edge in the body topology must be used by exactly two face-side incidences.+ - therefore open-boundary edges (incidence 1), dangling/unused edges (0), or non-manifold edges (>2) fail `expect_manifold`.++⚠️ Severity for all validation ops (`expect_exists`, `expect_selectable`, `expect_manifold`): failures are diagnostic-only warning outcomes. They do **not** by themselves block compile success or STEP export.### Export semantics- Export body policy is fixed: last successfully executed geometric body by source op index.- Failed later booleans do not invalidate earlier successful bodies.- Partial execution can still produce a valid STEP file that silently omits intended later features.- Validation ops never become export bodies.+- Validation-op failures can coexist with successful STEP export (because they are diagnostic-only).- Output STEP text represents the selected body in world coordinates after all default-frame and placement transforms already applied.- Firmament world coordinates map directly to STEP geometry coordinates (no additional global remap in exporter).diff --git a/references/firmament/07-semantic-mismatches-and-gotchas.md b/references/firmament/07-semantic-mismatches-and-gotchas.mdindex d48d014b..987120d7 100644--- a/references/firmament/07-semantic-mismatches-and-gotchas.md+++ b/references/firmament/07-semantic-mismatches-and-gotchas.md@@ -98,6 +98,8 @@ Trap: using one target style uniformly for all validation ops.`expect_selectable.count` is exact-match and `count: 0` means "expect none" (passes only on zero resolved elements). Failures produce warnings, not execution aborts.+⚠️ Severity trap: all three validation ops (`expect_exists`, `expect_selectable`, `expect_manifold`) are diagnostic-only at execution. Failed validations produce warning diagnostics but do not by themselves fail compile or block export.+---## 11) `model.units` is required but currently unconstrained as an enum@@ -118,6 +120,8 @@ Trap: expecting final validation op target to become export body.⚠️ Partial execution trap: if a later boolean fails, earlier successful geometry is still exported. This can look like success while silently truncating intended features.+Validation failures can still appear alongside successful compile/export because they are warning-only diagnostics.+---## 13) Source-of-truth hierarchy@@ -147,5 +151,27 @@ Trap: expecting PMI entries to affect geometry/export semantics in current imple## 17) `intersect` is implemented but narrow`intersect` uses `left` as its primary reference field (`left` role mirrors `from`/`to` in other boolean ops) and executes through the general boolean path.+Positive behavior: it computes geometric overlap (`left ∩ with`) when that overlap is representable inside the currently supported bounded subset.Trap: assuming it participates in safe subtract continuation semantics. It does not; treat as narrow subset behavior unless test-backed.++## 18) Pointed-cone cap selectors can legally parse but resolve empty++Cone selector ports include `top_face`/`bottom_face`, but runtime counts actual topology.++- `top_radius: 0` pointed cone ⇒ no top cap face ⇒ `top_face` resolves to zero elements.+- `bottom_radius: 0` pointed cone ⇒ no bottom cap face ⇒ `bottom_face` resolves to zero elements.++Trap: assuming compile-time port allowance guarantees runtime non-empty selector results.++## 19) Enclosed-void policy is export-blocking in non-allowing modes++For default/no schema, `cnc`, and `injection_molded`, enclosed void detection is a hard compile failure (error diagnostic), not a warning.++Trap: treating "void rejected" as advisory. A fully enclosed cavity (for example an internal spherical cavity) prevents successful compile/export in those modes. `additive` is the allowing mode.++## 20) Pattern marker substrings are effectively reserved in generated IDs++Pattern expansion synthesizes IDs with `__linN` and `__cirN`, and executor logic treats feature IDs containing `__lin`/`__cir` as pattern-generated behavior cues.++⚠️ Avoid manually authoring feature IDs that contain `__lin` or `__cir` substrings unless you intentionally want that pattern-generated classification behavior.diff --git a/references/firmament/08-worked-examples.md b/references/firmament/08-worked-examples.mdindex 1177930f..50e9d008 100644--- a/references/firmament/08-worked-examples.md+++ b/references/firmament/08-worked-examples.md@@ -205,6 +205,7 @@ Interpretation:- `expect_exists` selector target is allowed.- `expect_selectable` requires selector target + integer count.- `expect_manifold` requires bare feature ID target.+- If one of these validations fails, compile can still succeed and export can still return STEP (validation failures are warning diagnostics, not hard export blockers).- Export body remains `hole` because it is the last executed geometric body (validation ops do not replace export selection).---diff --git a/references/firmament/README.md b/references/firmament/README.mdindex 46a3cc4f..47f0b099 100644--- a/references/firmament/README.md+++ b/references/firmament/README.md@@ -20,3 +20,6 @@ Goal: let a fresh model write correct Firmament without guessing hidden semanticThis reference is anchored to current repository behavior (parser/validators/lowering/execution/tests/examples), not aspirational language design.Use this folder as the **primary authoring reference** for LLM-generated `.firmament` in this repo.++Integration boundary note: this corpus focuses on file-authoring semantics, not full caller-facing compiler API contracts.+Integrators should inspect `Aetheris.Kernel.Firmament/FirmamentCompileResult.cs`, `Aetheris.Kernel.Firmament/FirmamentCompilationArtifact.cs`, and integration tests under `Aetheris.Kernel.Firmament.Tests`.