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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.