Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

docs: add Firmament LLM reference corpus

Yuechen Li73de347d58a4
diff --git a/references/firmament/01-language-overview-and-pipeline.md b/references/firmament/01-language-overview-and-pipeline.md
new file mode 100644
index 00000000..61a453c7
--- /dev/null
+++ b/references/firmament/01-language-overview-and-pipeline.md
@@ -0,0 +1,50 @@
+# Firmament Overview and Compile Pipeline
+
+## What Firmament is
+
+Firmament is an ordered CAD-feature DSL that compiles to executable primitive/boolean operations over Aetheris BRep bodies.
+
+- It is **feature-id based** and **document-order dependent**.
+- It supports primitive creation, bounded boolean composition, validation ops, and a narrow pattern expansion subset.
+- It supports TOON-style canonical syntax and JSON-compat parse mode.
+
+## What Firmament is not
+
+Firmament is **not** currently:
+
+- a general parametric constraint solver,
+- a full frame/assembly language,
+- a generalized selector graph traversal language,
+- a general robust boolean engine for arbitrary solids.
+
+## Execution model (current)
+
+Compile flow today:
+
+1. Parse source (`TOON` or JSON object root).
+2. Validate schema block (if present).
+3. Validate primitive required fields.
+4. Validate boolean required fields.
+5. Validate pattern required fields.
+6. Validate validation-op required fields + target shape classification.
+7. Enforce document coherence (references, selector roots/ports, pattern expansion).
+8. Map schema into compiled schema model.
+9. Run CNC DFM checks (narrow current rule).
+10. Lower primitives/booleans.
+11. Execute primitives then booleans.
+12. Enclosed-void schema guard.
+13. Run validation ops against executed geometry.
+
+The returned artifact includes parsed doc, compiled schema, lowered plan, primitive/boolean execution result, and validation execution result.
+
+## Identity and ordering semantics
+
+- Feature IDs must be unique across feature-producing ops.
+- Boolean primary reference fields (`to`, `from`, `left`) must reference earlier produced IDs.
+- Pattern ops expand into synthesized IDs (`__linN`, `__cirN`) and become concrete feature-producing boolean entries.
+- Validation ops do not create geometry.
+
+## Export-selection semantics
+
+Export chooses the **last successfully executed geometric body by op index** (primitive or boolean).
+Validation ops are never export bodies.
diff --git a/references/firmament/02-file-shape-and-sections.md b/references/firmament/02-file-shape-and-sections.md
new file mode 100644
index 00000000..6c5574d3
--- /dev/null
+++ b/references/firmament/02-file-shape-and-sections.md
@@ -0,0 +1,73 @@
+# File Shape, Sections, and Canonical Authoring Form
+
+## Canonical source form
+
+Repository corpus style is TOON-style indentation syntax in `.firmament` files.
+JSON is parser-compatible but non-canonical for corpus authoring.
+
+## Required top-level sections
+
+Required:
+
+- `firmament` (object-like)
+- `model` (object-like)
+- `ops` (array-like)
+
+Optional:
+
+- `schema` (object-like)
+- `pmi` (array-like)
+
+Unknown top-level sections are rejected.
+
+## Required top-level fields
+
+- `firmament.version` required.
+- `model.name` required.
+- `model.units` required.
+
+## Ops structure
+
+- `ops[n]:` header defines count in canonical TOON style.
+- Each entry begins with `-` and contains an object-like block including `op`.
+- `op` token must map to known op kind.
+
+## Known op kinds (current)
+
+Primitive:
+
+- `box`, `cylinder`, `cone`, `torus`, `sphere`
+
+Boolean:
+
+- `add`, `subtract`, `intersect`
+
+Validation:
+
+- `expect_exists`, `expect_selectable`, `expect_manifold`
+
+Pattern:
+
+- `pattern_linear`, `pattern_circular`
+
+## Section ordering note
+
+Human docs recommend fixed section order (`firmament`, `model`, optional `schema`, `ops`, optional `pmi`).
+Current parser enforces section presence/shape but not strict relative order; do not rely on relaxed behavior for canonical corpus.
+
+## Schema block (current validation semantics)
+
+When `schema` is present:
+
+- `process` required and must be one of: `cnc`, `injection_molded`, `additive`.
+- `cnc` requires `minimum_tool_radius > 0`.
+- `injection_molded` requires:
+ - `parting_plane` in `xy|yz|xz`
+ - `gate_location` object-like with numeric `x,y,z`
+ - `draft_angle > 0`
+- `additive` requires `printer_resolution > 0`.
+
+Additional current behavior:
+
+- CNC DFM currently checks subtract-tool cylinder `with.radius >= minimum_tool_radius`.
+- Enclosed voids are rejected for non-additive process modes.
diff --git a/references/firmament/03-primitives-and-local-frames.md b/references/firmament/03-primitives-and-local-frames.md
new file mode 100644
index 00000000..a73ec4e6
--- /dev/null
+++ b/references/firmament/03-primitives-and-local-frames.md
@@ -0,0 +1,93 @@
+# Primitive Definitions, Parameters, and Local Frames
+
+This section defines each currently supported primitive, required fields, constraints, and default spatial frame behavior.
+
+## Common primitive rules
+
+All primitives require:
+
+- `op`
+- `id` (non-empty scalar)
+
+Optional:
+
+- `place` block (legacy or semantic placement)
+
+## `box`
+
+Fields:
+
+- `size[3]` required; all components numeric and `> 0`.
+
+Semantics:
+
+- 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).
+
+## `cylinder`
+
+Fields:
+
+- `radius` required, numeric `> 0`
+- `height` required, numeric `> 0`
+
+Semantics:
+
+- 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]`.
+
+## `cone`
+
+Fields:
+
+- `bottom_radius` required, numeric `>= 0`
+- `top_radius` required, numeric `>= 0`
+- `height` required, numeric `> 0`
+
+Constraints:
+
+- Not both radii zero.
+- If both radii > 0, they must be unequal.
+
+Semantics:
+
+- 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.
+
+## `sphere`
+
+Fields:
+
+- `radius` required, numeric `> 0`
+
+Semantics:
+
+- 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.
+
+## `torus`
+
+Fields:
+
+- `major_radius` required, numeric `> 0`
+- `minor_radius` required, numeric `> 0`
+- constraint: `major_radius > minor_radius`
+
+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 primitive kind
+
+- 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`
+
+These contracts are compile-time selector guards and influence placement/validation legality.
diff --git a/references/firmament/04-placement-semantics.md b/references/firmament/04-placement-semantics.md
new file mode 100644
index 00000000..4675696d
--- /dev/null
+++ b/references/firmament/04-placement-semantics.md
@@ -0,0 +1,89 @@
+# Placement Semantics (Deep Reference)
+
+Placement is represented by `place` block and parsed into:
+
+- legacy anchor: `on`, `offset`
+- semantic subset: `on_face`, `centered_on`, `around_axis`, `radial_offset`, `angle_degrees`
+
+Unknown keys are rejected.
+
+## `place.on`
+
+Accepted anchors:
+
+- `origin`
+- selector-shaped token `feature.port`
+
+Meaning:
+
+- establishes anchor point source unless semantic anchors are provided.
+
+Runtime anchor extraction from selector:
+
+- face/face-set ports: representative face points, centroided.
+- edge-set ports: edge endpoint point cloud centroid.
+- vertex-set ports: vertex point cloud centroid.
+
+## `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.
+
+## `place.on_face`
+
+- 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.
+
+## `place.centered_on`
+
+- 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`
+
+- 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.
+
+## `place.radial_offset`
+
+- Numeric scalar radius from axis.
+- Requires `around_axis` (validated).
+- Defaults to 0 when omitted while `around_axis` present.
+
+## `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.
+
+## Composition order inside placement resolver
+
+For primitives and booleans:
+
+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`).
+
+## Primitive execution placement application
+
+Primitive publish flow:
+
+1. Build raw primitive body.
+2. Apply default local frame publish shift (`box/cylinder/cone` +Z half-height).
+3. Apply placement translation computed above.
+
+This means final published primitive position includes both default-frame shift and placement translation.
+
+## Boolean placement application nuances
+
+Boolean placement may apply differently depending on path:
+
+- 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.
+
+This distinction is behaviorally significant and documented as a mismatch/gotcha in `07-semantic-mismatches-and-gotchas.md`.
diff --git a/references/firmament/05-booleans-safe-families-patterns.md b/references/firmament/05-booleans-safe-families-patterns.md
new file mode 100644
index 00000000..6212a656
--- /dev/null
+++ b/references/firmament/05-booleans-safe-families-patterns.md
@@ -0,0 +1,84 @@
+# Booleans, Bounded Families, and Pattern Continuation
+
+## Boolean ops and required shape
+
+Supported boolean ops:
+
+- `add` requires `id`, `to`, `with`
+- `subtract` requires `id`, `from`, `with`
+- `intersect` requires `id`, `left`, `with`
+
+`with` must be object-like with nested primitive tool `op`.
+
+Nested tool parameter validation exists for: box/cylinder/sphere/cone/torus.
+
+## Safe-family model (current implemented boundary)
+
+The system enforces a bounded feature-graph model via explicit state tracking.
+
+Key states:
+
+- `BoxRoot`
+- `CylinderRoot`
+- `BoundedOrthogonalAdditiveSafeRoot`
+- `BoundedOrthogonalAdditiveOutsideSafeRoot`
+- `SafeSubtractComposition`
+- `Other`
+
+### Orthogonal additive unions
+
+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.
+
+### Subtract re-entry rule
+
+Subtract with safe-hole tools (`cylinder`/`cone`) may:
+
+- start from bounded recognized roots,
+- continue from already validated safe subtract composition,
+- but cannot re-enter from arbitrary `Other` states.
+
+### Hole families / continuation
+
+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
+
+### Counterbore/blind/coaxial notes
+
+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.
+
+### Independent multi-hole continuation
+
+Pattern expansion and sequential subtracts can produce multi-hole chains, but only within current safe subtract family and non-interfering analytic constraints.
+
+## Pattern family (P2 subset)
+
+Supported pattern ops:
+
+- `pattern_linear`
+- `pattern_circular`
+
+Constraints:
+
+- `source` must reference earlier feature.
+- Source currently must be a `subtract` boolean feature.
+
+`pattern_linear`:
+
+- 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`:
+
+- 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 is compile-time document transformation before lowering/execution.
diff --git a/references/firmament/06-supported-vs-deferred.md b/references/firmament/06-supported-vs-deferred.md
new file mode 100644
index 00000000..27ad102f
--- /dev/null
+++ b/references/firmament/06-supported-vs-deferred.md
@@ -0,0 +1,29 @@
+# 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)
+
+## Deferred / unsupported / unsafe-to-assume
+
+- General unrestricted boolean support 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.
+
+## Authoring rule for LLMs
+
+If requirement lies outside explicitly proven subset (examples + tests + safe-family rules), treat it as deferred and avoid speculative source generation.
diff --git a/references/firmament/07-semantic-mismatches-and-gotchas.md b/references/firmament/07-semantic-mismatches-and-gotchas.md
new file mode 100644
index 00000000..65c76832
--- /dev/null
+++ b/references/firmament/07-semantic-mismatches-and-gotchas.md
@@ -0,0 +1,78 @@
+# Semantic Mismatches, Suspected Mismatches, and LLM Gotchas
+
+This file is intentionally explicit about places where intended language semantics and current behavior may diverge.
+
+## Known mismatch: module README vs actual implementation
+
+`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.
+
+## Known mismatch: section-order guidance vs parser behavior
+
+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
+
+`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.
+
+LLM trap: assuming every primitive anchors at geometric center or at Z=0 plane identically.
+
+## Known mismatch risk: boolean placement timing differs by path
+
+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.
+
+## Known/suspected mismatch: `centered_on` name implies richer behavior than implemented
+
+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.
+
+LLM trap: assuming automatic orientation alignment when using `centered_on`.
+
+## Known/suspected mismatch: semantic placement selector ports vs runtime extraction
+
+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.
+
+## Known mismatch risk: patterns chain booleans, not independent clones
+
+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.
+
+## Known mismatch risk: safety-family state is stricter than op availability
+
+Even if parser accepts a boolean op and tool kind, safe-family graph rules may reject composition order or family re-entry.
+
+LLM trap: assuming syntactically valid subtract chains are always executable.
+
+## Placement gotchas
+
+- `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.
+
+## Boolean gotchas
+
+- `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
+
+Before generating high-stakes geometry, verify against current tests/examples for:
+
+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.
diff --git a/references/firmament/README.md b/references/firmament/README.md
new file mode 100644
index 00000000..316ce360
--- /dev/null
+++ b/references/firmament/README.md
@@ -0,0 +1,21 @@
+# Firmament Reference Corpus (LLM Authoring)
+
+This folder is the canonical, implementation-grounded Firmament reference pass for **LLM authors**.
+
+Goal: let a fresh model write correct Firmament without guessing hidden semantics.
+
+## Reading order
+
+1. `01-language-overview-and-pipeline.md`
+2. `02-file-shape-and-sections.md`
+3. `03-primitives-and-local-frames.md`
+4. `04-placement-semantics.md`
+5. `05-booleans-safe-families-patterns.md`
+6. `06-supported-vs-deferred.md`
+7. `07-semantic-mismatches-and-gotchas.md`
+
+## Scope
+
+This reference is anchored to current repository behavior (parser/validators/lowering/execution/tests/examples), not aspirational language design.
+
+Use this folder as the **primary authoring reference** for LLM-generated `.firmament` in this repo.