Skip to content

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.md
index 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.md
index 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.md
index 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.md
index 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 contracts
Supported 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.md
index 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.md
index 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.md
new file mode 100644
index 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.md
index 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 semantic
5. `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