Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

docs(firmament): clarify DOC3 semantic edge cases and traps

Yuechen Lia10f296e34c3
diff --git a/references/firmament/02-file-shape-and-sections.md b/references/firmament/02-file-shape-and-sections.md
index 7e1df543..22888c56 100644
--- a/references/firmament/02-file-shape-and-sections.md
+++ b/references/firmament/02-file-shape-and-sections.md
@@ -73,3 +73,7 @@ Additional current behavior:
- CNC DFM currently checks subtract-tool cylinder `with.radius >= minimum_tool_radius`.
- Enclosed voids are rejected for non-additive process modes.
+
+## PMI behavior (current)
+
+`pmi` section presence is parsed/tracked (`HasPmi`) but currently does not alter execution, validation outcomes, or STEP output content. Treat `pmi` as no-op metadata in current milestone state.
diff --git a/references/firmament/03-primitives-and-local-frames.md b/references/firmament/03-primitives-and-local-frames.md
index 2b91f821..aa8f879d 100644
--- a/references/firmament/03-primitives-and-local-frames.md
+++ b/references/firmament/03-primitives-and-local-frames.md
@@ -127,7 +127,7 @@ Cone behaves like box/cylinder for vertical anchoring in default frame: placemen
No shift in `ApplyDefaultLocalFrame`.
### Placement resolver correction (primitive-specific)
-Primitive placement translation adds `+radius` in Z.
+Primitive placement translation adds `+radius` in Z **only when a `place` block exists**.
### Final default span with no `place`
With no `place`, translation resolver returns zero (no placement block), so sphere remains centered at origin:
@@ -135,8 +135,15 @@ With no `place`, translation resolver returns zero (no placement block), so sphe
- `z ∈ [-radius,+radius]`
### Important placement consequence
-When a `place` block exists (even zero offset), sphere gets the extra `+radius` Z correction.
-Example: `on: base.top_face` at `z=4`, `radius=3`, zero offset ⇒ center at `z=7` (tangent contact), not `z=4`.
+When a `place` block exists (even zero offset or `on: origin`), sphere gets the extra `+radius` Z correction.
+
+⚠️ **Trap:** `place: { on: origin, offset:[0,0,0] }` is **not** equivalent to omitting `place`.
+
+Minimal difference example (`radius: 3`):
+- no `place` block ⇒ center at `z=0`
+- `place.on: origin` + zero offset ⇒ center at `z=3`
+
+Example with selector anchor: `on: base.top_face` at `z=4`, `radius=3`, zero offset ⇒ center at `z=7` (tangent contact), not `z=4`.
---
@@ -154,7 +161,7 @@ Example: `on: base.top_face` at `z=4`, `radius=3`, zero offset ⇒ center at `z=
No shift in `ApplyDefaultLocalFrame`.
### Placement resolver correction (primitive-specific)
-Primitive placement translation adds `+minor_radius` in Z.
+Primitive placement translation adds `+minor_radius` in Z **only when a `place` block exists**.
### Final default span with no `place`
With no `place`, torus remains centered at origin:
@@ -162,7 +169,10 @@ With no `place`, torus remains centered at origin:
- vertical span `z ∈ [-minor_radius,+minor_radius]`
### Important placement consequence
-When a `place` block exists, torus gets the extra `+minor_radius` correction.
+When a `place` block exists (even zero offset or `on: origin`), torus gets the extra `+minor_radius` correction.
+
+⚠️ **Trap:** `place: on: origin` is not equivalent to no `place` block for torus either.
+
Example: anchor on `z=4`, `minor_radius=2`, zero offset ⇒ center at `z=6`.
---
@@ -179,3 +189,5 @@ These are compile-time contracts used by placement and validation target checks.
- Boolean results (`add`/`subtract`/`intersect`): `top_face`, `bottom_face`, `side_faces`, `edges`, `vertices`
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.
diff --git a/references/firmament/05-booleans-safe-families-patterns.md b/references/firmament/05-booleans-safe-families-patterns.md
index f33dbda3..5c3eaaf4 100644
--- a/references/firmament/05-booleans-safe-families-patterns.md
+++ b/references/firmament/05-booleans-safe-families-patterns.md
@@ -9,10 +9,14 @@ Supported boolean ops:
- `subtract`: requires `id`, `from`, `with`
- `intersect`: requires `id`, `left`, `with`
+`left` is the primary reference field for `intersect` and is equivalent in role to `from` (subtract) / `to` (add): it names the already-existing feature body that the boolean starts from.
+
`with` must be a nested primitive tool object-like value.
Supported tool ops inside `with`:
- `box`, `cylinder`, `sphere`, `cone`, `torus`
+⚠️ `with.place` is not a supported tool field. Placement is read only from the boolean's top-level `place` block. Nested placement-like fields under `with` are ignored by execution.
+
---
## Boolean result selector ports
@@ -26,6 +30,8 @@ All boolean result features (`add`/`subtract`/`intersect`) expose the same selec
This is intentionally not a union of all primitive-tool ports.
+⚠️ These boolean ports are heuristic (normal/classification based), not robust topology identities. Do not rely on boolean `top_face`/`bottom_face` ports for rotated or complex geometry.
+
---
## Boolean reference fields vs placement anchors
@@ -70,6 +76,8 @@ 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.
+
Anything outside this family should be treated as deferred/unsupported unless explicitly test-backed.
---
@@ -109,6 +117,12 @@ Required:
`step[3]` meaning:
- world-space translation delta added per instance
- instance `i` gets offset contribution `i * step`
+- final instance offset is `source_offset + (i * step)` (step accumulates on top of source placement; it is not absolute placement)
+
+Worked accumulation example:
+- source `offset = [5, 0, 0]`
+- `step = [10, 0, 0]`
+- generated offsets: `lin1=[15,0,0]`, `lin2=[25,0,0]`, `lin3=[35,0,0]`
Synthesized IDs:
- `source__lin1`, `source__lin2`, ... `source__linN`
@@ -131,7 +145,14 @@ Expansion behavior:
- cloned placement injects `around_axis = axis`
- `radial_offset` defaults to `0` if absent on source placement
- angle per instance uses either explicit step or `span / count`
-- base source placement angle (if any) is included
+- instance angle is `baseAngle + (i * angularStep)`
+- `baseAngle` is the source placement `angle_degrees` value (if absent: 0)
+- pattern does not reset angle to zero
+
+Worked angle example:
+- source `angle_degrees = 30`
+- pattern `angle_step_degrees = 45`, `count=3`
+- generated angles: `cir1=75`, `cir2=120`, `cir3=165`
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 0b4b97fa..70eb9fed 100644
--- a/references/firmament/06-supported-vs-deferred.md
+++ b/references/firmament/06-supported-vs-deferred.md
@@ -48,10 +48,15 @@ This file is the capability boundary for LLM authoring.
Execution semantics:
- `expect_exists`: executes for feature-id and selector targets.
- `expect_selectable`: selector targets only (bare feature-id not supported at execution).
+ - `count` is an exact-match expectation (`resolved_count == count`), not a minimum.
+ - `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).
### 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.
- 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 3e85b800..d48d014b 100644
--- a/references/firmament/07-semantic-mismatches-and-gotchas.md
+++ b/references/firmament/07-semantic-mismatches-and-gotchas.md
@@ -17,11 +17,11 @@ No `place` block:
- sphere center remains at origin
- torus center remains at origin
-With `place` block:
+With `place` block (including `place.on: origin` with zero offset):
- sphere gets extra `+radius Z`
- torus gets extra `+minor_radius Z`
-Trap: thinking these corrections apply globally even without placement.
+Trap: thinking these corrections apply globally even without placement, or assuming `place.on: origin` == no placement block.
---
@@ -76,6 +76,8 @@ Each generated boolean references previous generated instance as primary source.
Trap: assuming instance `N` subtracts from original source body directly.
+Also: linear pattern `step` accumulates on top of source offset (`source_offset + i*step`), and circular pattern angle accumulates on top of source angle (`baseAngle + i*angularStep`).
+
---
## 9) Safe-family acceptance is stricter than syntax validity
@@ -94,6 +96,8 @@ Trap: assuming parser/required-field success implies executable support.
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.
+
---
## 11) `model.units` is required but currently unconstrained as an enum
@@ -107,14 +111,41 @@ Trap: assuming units string changes internal scaling. Current pipeline exports c
## 12) Export body selection ignores validation ops
-Export always chooses the last executed primitive/boolean body by source order.
+Export always chooses the last successfully executed primitive/boolean body by source order.
Validation ops affect diagnostics, not exported body selection.
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.
+
---
## 13) Source-of-truth hierarchy
Some older human-readable docs may lag implementation status.
For semantic disputes, trust parser/validation/lowering/execution code and tests over stale module summaries.
+
+
+## 14) `with.place` is ignored
+
+Boolean tool objects do not support nested placement semantics.
+
+Trap: writing `with.place` expecting tool motion. Placement must be authored at boolean top-level `place`.
+
+## 15) Boolean selector ports are heuristic
+
+Boolean result ports (for example `top_face`) rely on classification heuristics (such as normal-direction filters), not guaranteed topological identity.
+
+Trap: relying on these ports for rotated or complex boolean outcomes.
+
+## 16) `pmi` is currently no-op metadata
+
+`pmi` is parsed as section presence but currently does not change execution behavior or STEP export payload.
+
+Trap: expecting PMI entries to affect geometry/export semantics in current implementation.
+
+## 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.
+
+Trap: assuming it participates in safe subtract continuation semantics. It does not; treat as narrow subset behavior unless test-backed.
diff --git a/references/firmament/08-worked-examples.md b/references/firmament/08-worked-examples.md
index 926a98ce..1177930f 100644
--- a/references/firmament/08-worked-examples.md
+++ b/references/firmament/08-worked-examples.md
@@ -259,3 +259,139 @@ ops[5]:
```
This demonstrates targeting a synthesized pattern-generated feature ID in later validation.
+
+
+## 7) Sphere placement edge case: no `place` vs `place.on: origin`
+
+```toon
+firmament:
+ version: 1
+
+model:
+ name: ex_sphere_place_origin_difference
+ units: mm
+
+ops[2]:
+ -
+ op: sphere
+ id: s_no_place
+ radius: 3
+ -
+ op: sphere
+ id: s_with_place
+ radius: 3
+ place:
+ on: origin
+ offset[3]:
+ 0
+ 0
+ 0
+```
+
+Key difference:
+- `s_no_place` center is at `z=0`.
+- `s_with_place` center is at `z=3` because any `place` block activates sphere `+radius` correction.
+
+---
+
+## 8) Linear pattern accumulation with non-zero source offset
+
+```toon
+firmament:
+ version: 1
+
+model:
+ name: ex_linear_offset_accumulation
+ units: mm
+
+ops[3]:
+ -
+ op: box
+ id: plate
+ size[3]:
+ 80
+ 20
+ 8
+ -
+ op: subtract
+ id: seed
+ from: plate
+ with:
+ op: cylinder
+ radius: 2
+ height: 20
+ place:
+ on: plate.top_face
+ offset[3]:
+ 5
+ 0
+ 0
+ -
+ op: pattern_linear
+ source: seed
+ count: 3
+ step[3]:
+ 10
+ 0
+ 0
+```
+
+Generated offsets are cumulative from source offset:
+- `seed__lin1`: `[15,0,0]`
+- `seed__lin2`: `[25,0,0]`
+- `seed__lin3`: `[35,0,0]`
+
+---
+
+## 9) Circular pattern angle composition with non-zero base angle
+
+```toon
+firmament:
+ version: 1
+
+model:
+ name: ex_circular_angle_composition
+ units: mm
+
+ops[4]:
+ -
+ op: cylinder
+ id: flange
+ radius: 30
+ height: 8
+ -
+ op: cylinder
+ id: axis_ref
+ radius: 1
+ height: 20
+ -
+ op: subtract
+ id: seed
+ from: flange
+ with:
+ op: cylinder
+ radius: 2
+ height: 20
+ place:
+ on_face: flange.top_face
+ around_axis: axis_ref.side_face
+ radial_offset: 20
+ angle_degrees: 30
+ offset[3]:
+ 0
+ 0
+ 0
+ -
+ op: pattern_circular
+ source: seed
+ count: 3
+ axis: axis_ref.side_face
+ angle_step_degrees: 45
+```
+
+Generated instance angles:
+- `seed__cir1`: `75°`
+- `seed__cir2`: `120°`
+- `seed__cir3`: `165°`
+
+Pattern composes on top of base angle; it does not reset to zero.