Skip to content

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.md
index 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, primit
Export 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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 semantic
This 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`.