Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
docs(firmament): complete DOC2 reference correction and densification
Yuechen Li9aeb90db7341
diff --git a/references/firmament/02-file-shape-and-sections.md b/references/firmament/02-file-shape-and-sections.mdindex 6c5574d3..7e1df543 100644--- a/references/firmament/02-file-shape-and-sections.md+++ b/references/firmament/02-file-shape-and-sections.md@@ -26,6 +26,8 @@ Unknown top-level sections are rejected.- `model.name` required.- `model.units` required.+Current implementation note: units must be present but are not currently validated against a closed enum list; corpus convention is `mm`.+## Ops structure- `ops[n]:` header defines count in canonical TOON style.diff --git a/references/firmament/03-primitives-and-local-frames.md b/references/firmament/03-primitives-and-local-frames.mdindex a73ec4e6..2b91f821 100644--- a/references/firmament/03-primitives-and-local-frames.md+++ b/references/firmament/03-primitives-and-local-frames.md@@ -1,93 +1,181 @@-# Primitive Definitions, Parameters, and Local Frames+# Primitive Definitions, Parameters, and Default Spatial Frames-This section defines each currently supported primitive, required fields, constraints, and default spatial frame behavior.+This file is the spatial ground truth for primitive authoring.-## Common primitive rules+Use it when you need to answer:+- where a primitive exists **before** placement,+- what point acts as its effective placement anchor,+- what its default world-space Z span is with no `place` block,+- how placement math composes with default-frame corrections.-All primitives require:+## Common primitive rules+All primitive ops require:- `op`- `id` (non-empty scalar)Optional:+- `place` block (legacy anchor+offset or semantic subset)++All feature IDs must be unique and referencable by later ops.++---++## Default-frame model used by execution++Primitive execution applies transforms in this order:-- `place` block (legacy or semantic placement)+1. Create raw primitive body in kernel-local coordinates.+2. Apply primitive default local-frame publish transform (`box/cylinder/cone` only).+3. Apply placement translation from `FirmamentPlacementResolver`.++For primitives only, placement translation includes an extra local-frame correction for:+- `sphere`: `+radius` on Z+- `torus`: `+minor_radius` on Z++No primitive-local correction is applied in placement resolver for `box`, `cylinder`, or `cone`.++---## `box`-Fields:+### Required fields+- `size[3]` (numeric, each `> 0`)-- `size[3]` required; all components numeric and `> 0`.+### Raw body (before default frame)+`BrepPrimitives.CreateBox(sizeX,sizeY,sizeZ)` produces a box centered on origin:+- `x ∈ [-sizeX/2, +sizeX/2]`+- `y ∈ [-sizeY/2, +sizeY/2]`+- `z ∈ [-sizeZ/2, +sizeZ/2]`-Semantics:+### Default publish transform+Execution applies `+sizeZ/2` in Z.-- Dimensions interpreted as X, Y, Z extents.-- Underlying primitive is created at origin then translated by `+sizeZ/2` in Z as default local-frame publish transform.-- Published default body occupies approximately `z ∈ [0, sizeZ]` (before additional `place` translation).+### Final default span with no `place`+- `x ∈ [-sizeX/2, +sizeX/2]`+- `y ∈ [-sizeY/2, +sizeY/2]`+- `z ∈ [0, sizeZ]`++### Effective placement anchor intuition+Without placement, the bottom face lies on `z=0`. With selector-based placement on another top face, the box bottom lands on the anchor plane.++---## `cylinder`-Fields:+### Required fields+- `radius` (`> 0`)+- `height` (`> 0`)++### Raw body (before default frame)+`BrepPrimitives.CreateCylinder(radius,height)` is axis-aligned on Z and symmetric around `z=0`.-- `radius` required, numeric `> 0`-- `height` required, numeric `> 0`+### Default publish transform+Execution applies `+height/2` in Z.-Semantics:+### Final default span with no `place`+- axis stays parallel to global Z+- bottom cap at `z=0`+- top cap at `z=height`-- Axis is Z-axis in default construction.-- Underlying primitive then translated by `+height/2` in Z in publish path.-- Published default cylinder spans approximately `z ∈ [0, height]`.+### Effective placement anchor intuition+Placement anchoring tends to align the cylinder bottom cap to the anchor Z when `offset[2]=0`.++---## `cone`-Fields:+### Required fields+- `bottom_radius` (`>= 0`)+- `top_radius` (`>= 0`)+- `height` (`> 0`)++### Constraints+- Radii cannot both be zero.+- If both radii are positive, they must be different (`bottom_radius != top_radius`).++### Raw body construction arithmetic+Cone creation performs two internal transforms:+1. Revolve profile points `(bottom_radius,0)` → `(top_radius,height)` around Z.+2. Immediately translate by `-height/2` in Z inside `ExecuteCone`.-- `bottom_radius` required, numeric `>= 0`-- `top_radius` required, numeric `>= 0`-- `height` required, numeric `> 0`+Then primitive publish applies `+height/2` in Z (`ApplyDefaultLocalFrame`).-Constraints:+These two shifts cancel exactly.-- Not both radii zero.-- If both radii > 0, they must be unequal.+### Final default span with no `place`+Cone cap plane origins land at:+- lower cap: `z=0`+- upper cap: `z=height`-Semantics:+This holds for frustum and pointed variants (one cap may be absent when a radius is zero, but span arithmetic still uses `[0,height]`).-- Built via revolve profile along Z.-- Cone execution path recenters during construction then publish path applies `+height/2` Z shift.-- Published default cone occupies base/top along Z consistent with `z ∈ [0, height]` envelope.+### Effective placement anchor intuition+Cone behaves like box/cylinder for vertical anchoring in default frame: placement on a top face with zero offset starts its lower extent at anchor Z.++---## `sphere`-Fields:+### Required fields+- `radius` (`> 0`)++### Raw body (before default frame)+`BrepPrimitives.CreateSphere(radius)` is centered at origin.++### Default publish transform+No shift in `ApplyDefaultLocalFrame`.-- `radius` required, numeric `> 0`+### Placement resolver correction (primitive-specific)+Primitive placement translation adds `+radius` in Z.-Semantics:+### Final default span with no `place`+With no `place`, translation resolver returns zero (no placement block), so sphere remains centered at origin:+- center `(0,0,0)`+- `z ∈ [-radius,+radius]`-- Raw sphere primitive is center-at-origin.-- Placement resolver applies extra primitive correction `+radius` in Z for primitive placement translation.-- Net published default center is elevated relative to origin unless placement counteracts it.+### 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`.++---## `torus`-Fields:+### Required fields+- `major_radius` (`> 0`)+- `minor_radius` (`> 0`)+- `major_radius > minor_radius`++### Raw body (before default frame)+`BrepPrimitives.CreateTorus(major,minor)` is centered at origin, axis along Z.++### Default publish transform+No shift in `ApplyDefaultLocalFrame`.++### Placement resolver correction (primitive-specific)+Primitive placement translation adds `+minor_radius` in Z.++### Final default span with no `place`+With no `place`, torus remains centered at origin:+- center `(0,0,0)`+- vertical span `z ∈ [-minor_radius,+minor_radius]`-- `major_radius` required, numeric `> 0`-- `minor_radius` required, numeric `> 0`-- constraint: `major_radius > minor_radius`+### Important placement consequence+When a `place` block exists, torus gets the extra `+minor_radius` correction.+Example: anchor on `z=4`, `minor_radius=2`, zero offset ⇒ center at `z=6`.-Semantics:+----- Raw torus primitive centered at origin with axis along Z.-- Placement resolver applies extra primitive correction `+minor_radius` in Z for primitive placement translation.+## Selector-port contracts by feature kind-## Selector-port contracts by primitive kind+These are compile-time contracts used by placement and validation target checks.- Box: `top_face`, `bottom_face`, `side_faces`, `edges`, `vertices`- Cylinder: `top_face`, `bottom_face`, `side_face`, `circular_edges`, `edges`, `vertices`- Cone: `top_face`, `bottom_face`, `side_face`, `circular_edges`, `edges`, `vertices`- Sphere: `surface`- Torus: `surface`, `edges`, `vertices`+- Boolean results (`add`/`subtract`/`intersect`): `top_face`, `bottom_face`, `side_faces`, `edges`, `vertices`-These contracts are compile-time selector guards and influence placement/validation legality.+Boolean result ports are intentionally box-like, not primitive-tool-like.diff --git a/references/firmament/04-placement-semantics.md b/references/firmament/04-placement-semantics.mdindex 4675696d..885741bc 100644--- a/references/firmament/04-placement-semantics.md+++ b/references/firmament/04-placement-semantics.md@@ -1,89 +1,136 @@-# Placement Semantics (Deep Reference)+# Placement Semantics (Anchor Frames, Offsets, and Timing)-Placement is represented by `place` block and parsed into:+This file defines what `place` means in executable terms.-- legacy anchor: `on`, `offset`-- semantic subset: `on_face`, `centered_on`, `around_axis`, `radial_offset`, `angle_degrees`+## Placement shape-Unknown keys are rejected.+Supported placement keys:+- `on`+- `offset`+- `on_face`+- `centered_on`+- `around_axis`+- `radial_offset`+- `angle_degrees`-## `place.on`+Unknown placement keys fail validation.-Accepted anchors:+Legacy mode (no semantic keys used):+- `place.on` required+- `place.offset` required and must be exactly 3 numeric components-- `origin`-- selector-shaped token `feature.port`+Semantic mode (any semantic key used):+- `place.on` can be omitted+- `offset` defaults to zero if omitted or malformed at runtime+- `radial_offset` requires `around_axis`-Meaning:+----- establishes anchor point source unless semantic anchors are provided.+## Anchor resolution order-Runtime anchor extraction from selector:+Base anchor point is resolved in this strict precedence:+1. `on_face` (selector)+2. `centered_on` (selector)+3. `on` (`origin` or selector)+4. if none above and `around_axis` exists: axis origin+5. otherwise: world origin `(0,0,0)`-- face/face-set ports: representative face points, centroided.-- edge-set ports: edge endpoint point cloud centroid.-- vertex-set ports: vertex point cloud centroid.+`on_face` and `centered_on` currently use the same centroid-like anchor extraction logic. Names are ergonomic; behavior is not full mating/alignment.-## `place.offset`+----- Expected exactly 3 numeric components.-- For legacy placement (no semantic fields), `on` and `offset` are both required by validators.-- At runtime, missing/invalid offset list resolves to zero vector.+## What selector anchors reference-## `place.on_face`+For selector anchors (`feature.port`), runtime extracts representative points from published geometry of earlier features:-- Selector-shaped semantic anchor.-- If present, preferred over `centered_on` and `on` for base anchor resolution.-- Semantically acts as a selector-derived anchor point, not full mating/alignment.+- Face/face-set ports: representative face points, then centroid.+- Edge-set ports: edge endpoint points, then centroid.+- Vertex-set ports: vertex points, then centroid.-## `place.centered_on`+Port legality is checked first by selector contracts, then runtime extraction heuristics apply.-- Selector-shaped semantic anchor.-- Used if `on_face` absent.-- Currently same anchor-point extraction mechanics as `on_face` (centroid-based), i.e., no richer alignment behavior.+----## `place.around_axis`+## What `offset[3]` means-- Selector-shaped axis source.-- Runtime axis resolution currently expects `side_face` on cylindrical/conical geometry.-- If neither `on_face`/`centered_on`/`on` is present, base anchor defaults to axis origin.+`offset` is a **world-space translation vector** `(dx,dy,dz)` added after anchor (and optional around-axis) resolution.-## `place.radial_offset`+It is **not** measured in local face tangent coordinates, tool coordinates, or axis-relative polar frame.-- Numeric scalar radius from axis.-- Requires `around_axis` (validated).-- Defaults to 0 when omitted while `around_axis` present.+So for `offset[3]: [1,-2,5]`, placement always adds +1 X, -2 Y, +5 Z in world axes.-## `place.angle_degrees`+----- Numeric scalar angular parameter in degrees.-- Used with around-axis radial basis (`u/v`) generated from world reference vectors.-- Defaults to 0 when omitted.+## Around-axis semantics-## Composition order inside placement resolver+When `around_axis` is present:-For primitives and booleans:+1. Resolve axis from selector (currently expects `side_face` on cylindrical/conical surfaces).+2. Project base anchor to that axis.+3. Build radial basis from world references.+4. Apply radial vector:+ - radius = `radial_offset` (default 0)+ - angle = `angle_degrees` (default 0)-1. Resolve semantic anchor point (`on_face` → `centered_on` → `on` → axis-origin fallback → origin fallback).-2. If `around_axis` provided, transform anchor to radial point using `radial_offset` + `angle_degrees`.-3. Add raw `offset` vector.-4. For primitives only: add primitive-specific local-frame correction (`sphere:+radius Z`, `torus:+minorRadius Z`).+This computes a new base point before `offset` is added.-## Primitive execution placement application+----Primitive publish flow:+## Primitive placement translation formula-1. Build raw primitive body.-2. Apply default local frame publish shift (`box/cylinder/cone` +Z half-height).-3. Apply placement translation computed above.+For primitives, final placement translation vector is:-This means final published primitive position includes both default-frame shift and placement translation.+`(anchorPoint - origin) + offset + primitiveLocalCorrection`-## Boolean placement application nuances+where primitiveLocalCorrection is:+- sphere: `(0,0,radius)`+- torus: `(0,0,minor_radius)`+- others: `(0,0,0)`-Boolean placement may apply differently depending on path:+Then execution applies this translation to the already default-framed primitive body.-- In semantic tool-placement path (notably some subtract-cylinder cases), placement is applied to tool before boolean.-- Otherwise boolean runs with unplaced tool, and resulting boolean body is translated afterward.+Equivalent primitive pipeline:+1. create raw primitive+2. apply default-frame publish shift (`box/cylinder/cone` only)+3. apply placement translation formula above-This distinction is behaviorally significant and documented as a mismatch/gotcha in `07-semantic-mismatches-and-gotchas.md`.+---++## Boolean placement translation formula++For booleans, placement resolver returns:++`(anchorPoint - origin) + offset`++(no sphere/torus-style primitive correction for boolean feature placement)++### Timing nuance (critical)+Boolean placement is path-dependent in execution:++- **Semantic tool-placement path**: tool body is default-framed (for box/cylinder/cone tools), then translated, then boolean runs.+- **General path**: boolean runs with unplaced tool, then final boolean result body is translated.++These are geometrically different operations in many cases.+Do not assume `place` always means “move tool before boolean.”++---++## Anchor/reference distinction for booleans++Boolean body reference fields and placement anchors are separate semantics:++- `from` / `to` / `left` choose the primary geometry input to boolean op.+- `place.on` / `place.on_face` / `place.centered_on` choose where placement anchor is sampled.++They can reference different features.++---++## Practical authoring checklist++Before writing placed features, verify:+1. selector root is an earlier feature ID,+2. selector port is allowed for that feature kind,+3. `offset` is a 3-number world vector,+4. sphere/torus placement includes extra +Z correction,+5. boolean placement timing assumptions match supported execution path.diff --git a/references/firmament/05-booleans-safe-families-patterns.md b/references/firmament/05-booleans-safe-families-patterns.mdindex 6212a656..f33dbda3 100644--- a/references/firmament/05-booleans-safe-families-patterns.md+++ b/references/firmament/05-booleans-safe-families-patterns.md@@ -1,23 +1,47 @@-# Booleans, Bounded Families, and Pattern Continuation+# Booleans, Safe-Family State, and Pattern Expansion-## Boolean ops and required shape+This file documents executable boolean and pattern semantics as implemented.++## Boolean op contractsSupported boolean ops:+- `add`: requires `id`, `to`, `with`+- `subtract`: requires `id`, `from`, `with`+- `intersect`: requires `id`, `left`, `with`++`with` must be a nested primitive tool object-like value.+Supported tool ops inside `with`:+- `box`, `cylinder`, `sphere`, `cone`, `torus`++---++## Boolean result selector ports++All boolean result features (`add`/`subtract`/`intersect`) expose the same selector contract:+- `top_face`+- `bottom_face`+- `side_faces`+- `edges`+- `vertices`-- `add` requires `id`, `to`, `with`-- `subtract` requires `id`, `from`, `with`-- `intersect` requires `id`, `left`, `with`+This is intentionally not a union of all primitive-tool ports.-`with` must be object-like with nested primitive tool `op`.+----Nested tool parameter validation exists for: box/cylinder/sphere/cone/torus.+## Boolean reference fields vs placement anchors-## Safe-family model (current implemented boundary)+Do not conflate these:-The system enforces a bounded feature-graph model via explicit state tracking.+- Reference field (`to`/`from`/`left`) chooses the primary boolean source feature.+- Placement anchor fields (`place.on`, `place.on_face`, etc.) choose anchor sampling for placement translation.-Key states:+A boolean can subtract from one feature while anchoring to another selector source.+---++## Safe-family state machine (implemented boundary)++Execution tracks feature graph states per produced feature ID:- `BoxRoot`- `CylinderRoot`- `BoundedOrthogonalAdditiveSafeRoot`@@ -25,60 +49,96 @@ Key states:- `SafeSubtractComposition`- `Other`-### Orthogonal additive unions+### Core implications++1. Subtract continuation is not purely syntax-based.+2. A parsed/validated boolean can still fail feature-graph safety checks.+3. Re-entry from `Other` into safe subtract continuation is blocked.++### Orthogonal additive transition-Add results can be recognized as bounded orthogonal safe roots.-If recognized, subtract safe-family continuation may proceed from that additive result.-If not recognized, safe-family subtract re-entry is blocked.+`add` may classify to:+- `BoundedOrthogonalAdditiveSafeRoot` (recognized safe), or+- `BoundedOrthogonalAdditiveOutsideSafeRoot` (recognized outside safe subset).-### Subtract re-entry rule+Subtract continuation from these states is guarded and narrower than generic boolean parsing suggests.-Subtract with safe-hole tools (`cylinder`/`cone`) may:+### Supported continuation family-- start from bounded recognized roots,-- continue from already validated safe subtract composition,-- but cannot re-enter from arbitrary `Other` states.+Current continuation family is intentionally narrow:+- follow-on op must be `subtract`+- follow-on tool kind must be `cylinder` or `cone`+- geometric guards enforce non-overlap/non-tangent/non-degenerate-safe constraints-### Hole families / continuation+Anything outside this family should be treated as deferred/unsupported unless explicitly test-backed.-Supported safe-hole continuation family is narrow:+----- follow-on boolean must be `subtract`-- follow-on tool kind must remain `cylinder` or `cone`-- analytic recognition + overlap/tangent guards are enforced by boolean graph validator path+## Placement timing inside booleans-### Counterbore/blind/coaxial notes+Boolean placement has two execution modes:-There is no general counterbore feature op family today.-Blind/coaxial-like outcomes can appear only when they fit current subtract + placement + kernel recognition constraints; do not assume dedicated semantics.+1. **Tool-placement mode** (selected path): place translated tool before boolean.+2. **Result-placement mode** (fallback/general): run boolean first, then translate resulting body.-### Independent multi-hole continuation+Pattern-generated booleans always place tool first in their dedicated execution branch.-Pattern expansion and sequential subtracts can produce multi-hole chains, but only within current safe subtract family and non-interfering analytic constraints.+This timing distinction is a major source of authoring mistakes.-## Pattern family (P2 subset)+----Supported pattern ops:+## Pattern ops (P2 subset)+Supported:- `pattern_linear`- `pattern_circular`-Constraints:+Both require:+- `source` referencing an earlier feature ID+- source feature must be a boolean `subtract`++Pattern ops themselves are **not** feature-producing geometry.+They are compile-time expansion directives that inject synthesized boolean ops.++### `pattern_linear`++Required:+- `count` positive integer+- `step[3]` numeric vector++`step[3]` meaning:+- world-space translation delta added per instance+- instance `i` gets offset contribution `i * step`++Synthesized IDs:+- `source__lin1`, `source__lin2`, ... `source__linN`++Reference chaining:+- each generated boolean rebinds its primary reference (`from`/`to`/`left`) to the previous instance ID+- first generated instance references original `source`++So generated instances are sequential composition, not independent clones from root.++### `pattern_circular`++Required:+- `count` positive integer+- `axis` selector+- exactly one of `angle_degrees` (span) or `angle_step_degrees`-- `source` must reference earlier feature.-- Source currently must be a `subtract` boolean feature.+Expansion behavior:+- synthesized IDs: `source__cir1..source__cirN`+- 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-`pattern_linear`:+Also chains primary boolean reference sequentially like linear pattern.-- requires `count > 0` integer, `step[3]` numeric.-- clones source boolean entries with synthesized IDs `source__linN`.-- chains primary boolean reference to previous instance.+----`pattern_circular`:+## When pattern expansion happens-- requires `count > 0`, `axis` selector.-- requires either `angle_degrees` (span) or `angle_step_degrees` (exclusive).-- clones source with `around_axis = axis` and adjusted `angle_degrees`, IDs `source__cirN`.-- chains primary boolean reference to previous instance.+Pattern expansion occurs during document coherence validation, before lowering/execution/export body selection.-Pattern expansion is compile-time document transformation before lowering/execution.+After expansion, downstream stages operate on concrete generated boolean entries as if authored directly.diff --git a/references/firmament/06-supported-vs-deferred.md b/references/firmament/06-supported-vs-deferred.mdindex 27ad102f..0b4b97fa 100644--- a/references/firmament/06-supported-vs-deferred.md+++ b/references/firmament/06-supported-vs-deferred.md@@ -1,29 +1,81 @@# What Works Reliably Today vs What Is Deferred-## Known working capabilities (confidence-high, test-backed)--- Parsing canonical TOON `.firmament` and JSON-object compatibility mode.-- Primitives: box, cylinder, cone (frustum/pointed constraints), sphere, torus.-- Validation ops: expect_exists, expect_selectable, expect_manifold.-- Selector-shaped target/anchor references with per-kind port contracts.-- Placement subset (`on`/`offset` + semantic keys) with runtime anchor extraction.-- Pattern subset: linear and circular expansion from subtract sources.-- Narrow boolean families validated by execution tests/examples:- - box/box add/intersect/subtract within proven subset examples- - box minus cylinder/cone hole families under safe-family constraints- - box minus contained sphere cavity (narrow)- - sequential cylinder/cone safe subtract continuation (non-overlap/tangent)+This file is the capability boundary for LLM authoring.++## Confidence-high, implementation-backed capabilities++### Parsing and document shape+- Canonical TOON `.firmament` parsing works.+- JSON-object parse mode works.+- Required sections/required fields are enforced.++### Model header+- `model.name` required scalar.+- `model.units` required scalar.+- Current implementation does **not** enforce a closed enum for units at parse/validation stage.+ - Corpus convention uses `mm`.++### Primitive execution+- Primitives: `box`, `cylinder`, `cone`, `sphere`, `torus`.+- Cone supports frustum and pointed variants under current radius constraints.+- Default-frame behavior is stable and test-backed.++### Placement subset+- Legacy placement (`on` + `offset[3]`) is validated.+- Semantic keys (`on_face`, `centered_on`, `around_axis`, `radial_offset`, `angle_degrees`) are validated with current constraints.+- Selector anchoring + centroid extraction path is executable.++### Boolean subset+- Core boolean ops parse/lower/execute in bounded families:+ - `add`, `subtract`, `intersect` with nested primitive tool ops.+- Safe-family validator enforces bounded continuation semantics.+- Boolean selector contracts are available for result bodies.++### Pattern subset (P2)+- `pattern_linear` and `pattern_circular` are supported.+- Source must be earlier `subtract` feature.+- Expansion produces synthesized booleans with chained references.++### Validation ops+- `expect_exists`+- `expect_selectable`+- `expect_manifold`++`target` classification supports:+- bare feature-id target (`feature_id`)+- selector-shaped target (`feature_id.port`)++Execution semantics:+- `expect_exists`: executes for feature-id and selector targets.+- `expect_selectable`: selector targets only (bare feature-id not supported at 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.+- 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).++---## Deferred / unsupported / unsafe-to-assume-- General unrestricted boolean support across arbitrary primitive combinations.+- General unrestricted booleans across arbitrary primitive combinations.- Unbounded rotated/tilted tool guarantees across all families.-- General semantic placement mating/alignment language (current is anchor/axis heuristic subset).-- Multi-hop/chained selector traversal (`a.top_face.edges` style).-- Full counterbore/countersink dedicated language constructs.-- Guaranteed support for all box+torus boolean forms (audited as unsupported set in tests/docs).-- Guaranteed support for every box+sphere / box+cone / box+cylinder geometric arrangement outside audited subset.+- Full mating/alignment placement language (current semantics are anchor+offset+axis heuristics).+- Multi-hop selector traversals (`a.top_face.edges` etc.).+- Dedicated counterbore/countersink high-level ops.+- Broad support for box+sphere / box+cone / box+cylinder / box+torus across arbitrary geometric configurations.+- Any assumption that pattern instances are independent from root (they are chained).++---++## LLM authoring policy-## Authoring rule for LLMs+If a requested construct is not explicitly covered by:+1. this capability list,+2. selector contracts,+3. safe-family rules,+4. current examples/tests,-If requirement lies outside explicitly proven subset (examples + tests + safe-family rules), treat it as deferred and avoid speculative source generation.+then treat it as deferred and avoid speculative generation.diff --git a/references/firmament/07-semantic-mismatches-and-gotchas.md b/references/firmament/07-semantic-mismatches-and-gotchas.mdindex 65c76832..3e85b800 100644--- a/references/firmament/07-semantic-mismatches-and-gotchas.md+++ b/references/firmament/07-semantic-mismatches-and-gotchas.md@@ -1,78 +1,120 @@-# Semantic Mismatches, Suspected Mismatches, and LLM Gotchas+# Semantic Mismatches, Traps, and Caution Areas-This file is intentionally explicit about places where intended language semantics and current behavior may diverge.+This file records behavior that is either surprising, path-dependent, or easy to misuse.-## Known mismatch: module README vs actual implementation+## 1) Primitive default anchors are not uniform-`Aetheris.Kernel.Firmament/README.md` still describes pre-M0 scaffold status, but parser/validators/lowering/execution/tests are implemented.-Treat code/tests as source of truth, not that README status text.+- Box/cylinder/cone use explicit default publish shift (`+height/2` or equivalent) and behave like bottom-on-Z0 defaults.+- Sphere/torus are origin-centered by default **unless placement is present**, then placement adds primitive-specific +Z correction.-## Known mismatch: section-order guidance vs parser behavior+Trap: assuming every primitive uses the same anchor convention.-Human docs prescribe fixed top-level order, but parser checks required sections/shape and unknown sections rather than strict ordering.-Use canonical order anyway to avoid future breakage.+----## Known/suspected mismatch: primitive placement anchor expectations+## 2) Sphere/torus placement correction only happens when `place` exists-`ApplyDefaultLocalFrame` already shifts box/cylinder/cone upward by half-height.-Placement resolver then adds extra primitive corrections for sphere/torus only.-Resulting default anchors are not uniform across primitives.+No `place` block:+- sphere center remains at origin+- torus center remains at origin-LLM trap: assuming every primitive anchors at geometric center or at Z=0 plane identically.+With `place` block:+- sphere gets extra `+radius Z`+- torus gets extra `+minor_radius Z`-## Known mismatch risk: boolean placement timing differs by path+Trap: thinking these corrections apply globally even without placement.-For some subtract-cylinder semantic cases, tool is placed before boolean; in other paths boolean result is translated after operation.-These are not equivalent for many geometries.+----LLM trap: assuming `place` always means “move the tool before operation.”-Current behavior is path-dependent.+## 3) `offset` is world-frame, not face-local frame-## Known/suspected mismatch: `centered_on` name implies richer behavior than implemented+`offset[3]` is always world XYZ translation after anchor resolution.-Runtime currently resolves `centered_on` by same selector-anchor centroid extraction style as `on_face`/`on` selector anchors.-No full frame alignment or orientation matching is applied.+Trap: treating `offset` as local UVN displacement on selected face.-LLM trap: assuming automatic orientation alignment when using `centered_on`.+----## Known/suspected mismatch: semantic placement selector ports vs runtime extraction+## 4) `on_face` / `centered_on` are anchor-point semantics, not full mating-Compile-time selector contracts permit certain ports by feature kind.-Runtime anchor extraction then uses heuristic geometric filters (e.g., plane normal Z tests, cylindrical/conical detection).-Port legality does not guarantee intuitive spatial result on complex bodies.+Both currently resolve selector anchor points with centroid-style extraction.+No automatic orientation/frame alignment is applied.-## Known mismatch risk: patterns chain booleans, not independent clones+Trap: assuming `centered_on` aligns normals/axes automatically.-Pattern expansion rewrites each generated boolean to reference previous generated feature (chain), not always the original source root.-This affects geometry accumulation and safe-family validation.+----LLM trap: assuming each pattern instance subtracts independently from original base.+## 5) Boolean placement timing is path-dependent-## Known mismatch risk: safety-family state is stricter than op availability+Some subtract-cylinder semantic paths place tool before boolean; other paths place result after boolean.+Pattern-generated booleans place tool first in dedicated path.-Even if parser accepts a boolean op and tool kind, safe-family graph rules may reject composition order or family re-entry.+Trap: assuming one universal placement timing rule.-LLM trap: assuming syntactically valid subtract chains are always executable.+----## Placement gotchas+## 6) Boolean field reference vs placement anchor are independent-- `radial_offset` without `around_axis` is invalid.-- selector must reference earlier feature id.-- selector port token must be legal for referenced feature kind.-- around-axis currently expects cylindrical/conical side-face axis extraction.+`from`/`to`/`left` pick boolean base feature.+`place.on*` picks anchor source for translation.-## Boolean gotchas+Trap: assuming anchor selector must equal primary boolean source ID.-- `with` supports primitive tool definitions only.-- broad mixed-primitive boolean families remain intentionally narrow/guarded.-- some unsupported requests fail late at execution with NotImplemented diagnostics despite passing early shape checks.+----## What to verify before relying on advanced semantics+## 7) Pattern ops are directives, not directly referenceable geometry-Before generating high-stakes geometry, verify against current tests/examples for:+`pattern_linear` / `pattern_circular` do not create bodies themselves.+They expand into synthesized booleans.-1. target primitive default-frame anchor assumptions,-2. boolean placement pre/post application path,-3. safe-family continuation state transitions,-4. pattern chaining expectations,-5. selector runtime anchor behavior on expected feature kind.+Trap: attempting selector/validation targets against pattern op IDs.+Use generated IDs (`__linN`, `__cirN`) instead.++---++## 8) Pattern instances are chained, not independent root clones++Each generated boolean references previous generated instance as primary source.++Trap: assuming instance `N` subtracts from original source body directly.++---++## 9) Safe-family acceptance is stricter than syntax validity++Syntactically valid boolean chains can still fail feature-graph safety guards.++Trap: assuming parser/required-field success implies executable support.++---++## 10) Validation op `target` support differs by op kind++- `expect_exists`: bare feature-id or selector-shaped target.+- `expect_selectable`: selector target only at execution.+- `expect_manifold`: bare feature-id only at execution.++Trap: using one target style uniformly for all validation ops.++---++## 11) `model.units` is required but currently unconstrained as an enum++Parser requires presence, but current implementation does not restrict to a fixed token list.+Corpus convention uses `mm`.++Trap: assuming units string changes internal scaling. Current pipeline exports coordinates as-authored numeric values.++---++## 12) Export body selection ignores validation ops++Export always chooses the last 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.++---++## 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.diff --git a/references/firmament/08-worked-examples.md b/references/firmament/08-worked-examples.mdnew file mode 100644index 00000000..926a98ce--- /dev/null+++ b/references/firmament/08-worked-examples.md@@ -0,0 +1,261 @@+# Worked Examples (Canonical, LLM-Oriented)++These examples are intentionally small and semantically explicit.+Use them as templates for generation.++## 1) Primitive example: box default frame++```toon+firmament:+ version: 1++model:+ name: ex_box_default+ units: mm++ops[1]:+ -+ op: box+ id: base+ size[3]:+ 10+ 20+ 30+```++Expected default extent (no placement):+- `x ∈ [-5, +5]`+- `y ∈ [-10, +10]`+- `z ∈ [0, 30]`++---++## 2) Placement example: sphere tangent to top face++```toon+firmament:+ version: 1++model:+ name: ex_sphere_contact+ units: mm++ops[2]:+ -+ op: box+ id: base+ size[3]:+ 8+ 8+ 4+ -+ op: sphere+ id: ball+ radius: 3+ place:+ on: base.top_face+ offset[3]:+ 0+ 0+ 0+```++Why center is `z=7` (not `z=4`):+- anchor from `base.top_face` gives `z=4`+- sphere placement adds primitive correction `+radius = +3`+- final center `z=7`++---++## 3) Boolean example: simple subtract family++```toon+firmament:+ version: 1++model:+ name: ex_box_hole+ units: mm++ops[2]:+ -+ op: box+ id: block+ size[3]:+ 30+ 20+ 10+ -+ op: subtract+ id: hole+ from: block+ with:+ op: cylinder+ radius: 4+ height: 20+ place:+ on: block.top_face+ offset[3]:+ 0+ 0+ 0+```++Notes:+- `from` chooses boolean source body.+- `place.on` chooses anchor source for translation.+- In some paths this placement is applied to tool before boolean; in others, result translation occurs after boolean.++---++## 4) Pattern example: linear chained subtracts++```toon+firmament:+ version: 1++model:+ name: ex_linear_pattern+ units: mm++ops[3]:+ -+ op: box+ id: plate+ size[3]:+ 60+ 20+ 8+ -+ op: subtract+ id: hole_seed+ from: plate+ with:+ op: cylinder+ radius: 2+ height: 20+ place:+ on: plate.top_face+ offset[3]:+ -20+ 0+ 0+ -+ op: pattern_linear+ source: hole_seed+ count: 3+ step[3]:+ 10+ 0+ 0+```++Expansion intent:+- generates `hole_seed__lin1`, `hole_seed__lin2`, `hole_seed__lin3`+- each instance adds `i * [10,0,0]` world offset to source placement+- each generated subtract chains from previous generated feature++---++## 5) Validation + export example++```toon+firmament:+ version: 1++model:+ name: ex_validation_export+ units: mm++ops[5]:+ -+ op: box+ id: base+ size[3]:+ 20+ 20+ 10+ -+ op: subtract+ id: hole+ from: base+ with:+ op: cylinder+ radius: 3+ height: 20+ place:+ on: base.top_face+ offset[3]:+ 0+ 0+ 0+ -+ op: expect_exists+ target: hole.top_face+ -+ op: expect_selectable+ target: hole.edges+ count: 4+ -+ op: expect_manifold+ target: hole+```++Interpretation:+- `expect_exists` selector target is allowed.+- `expect_selectable` requires selector target + integer count.+- `expect_manifold` requires bare feature ID target.+- Export body remains `hole` because it is the last executed geometric body (validation ops do not replace export selection).++---++## 6) Circular pattern example with synthesized target in validation++```toon+firmament:+ version: 1++model:+ name: ex_circular_pattern+ units: mm++ops[5]:+ -+ op: cylinder+ id: flange+ radius: 30+ height: 8+ -+ op: cylinder+ id: axis_ref+ radius: 1+ height: 20+ -+ op: subtract+ id: bolt_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: 0+ offset[3]:+ 0+ 0+ 0+ -+ op: pattern_circular+ source: bolt_seed+ count: 5+ axis: axis_ref.side_face+ angle_degrees: 300+ -+ op: expect_manifold+ target: bolt_seed__cir5+```++This demonstrates targeting a synthesized pattern-generated feature ID in later validation.diff --git a/references/firmament/README.md b/references/firmament/README.mdindex 316ce360..46a3cc4f 100644--- a/references/firmament/README.md+++ b/references/firmament/README.md@@ -1,6 +1,6 @@# Firmament Reference Corpus (LLM Authoring)-This folder is the canonical, implementation-grounded Firmament reference pass for **LLM authors**.+This folder is the canonical, implementation-grounded Firmament reference for **LLM authors**.Goal: let a fresh model write correct Firmament without guessing hidden semantics.@@ -13,6 +13,7 @@ Goal: let a fresh model write correct Firmament without guessing hidden semantic5. `05-booleans-safe-families-patterns.md`6. `06-supported-vs-deferred.md`7. `07-semantic-mismatches-and-gotchas.md`+8. `08-worked-examples.md`## Scope