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.mdindex 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.mdindex 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: placemenNo 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.mdindex 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 selecThis 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.mdindex 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.mdindex 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 hierarchySome 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.mdindex 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.