Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Clarify imported geometry recognition limits in syntax docs

Yuechen Li3aad55aa3593
diff --git a/docs/public/firmament/imported-feature-recognition.md b/docs/public/firmament/imported-feature-recognition.md
new file mode 100644
index 00000000..559b754b
--- /dev/null
+++ b/docs/public/firmament/imported-feature-recognition.md
@@ -0,0 +1,27 @@
+# Imported feature recognition: current limits
+
+`Recognize` currently binds explicit face references to a named region. Authored
+kind, confidence and optional evidence/proposals are not equivalent to automatic
+feature recognition or a complete geometric verification. Resolving a face ID
+proves which face was named; it does not prove that face is a hole wall.
+
+A bounded `Replace ... With Hole<Shaft>` path exists for one canonical imported
+body and one through-hole replacement. It rebuilds a Box plus a semantic shaft
+hole using the existing materializer, then exports STEP. Its report explicitly
+states `emissionStrategy: holeShaft-bounded-rebuild` and `residualSurgery: false`.
+Residual face counts are migration accounting, not proof of preserved residual
+geometry. This is not general hole resizing in an arbitrary imported part.
+
+The current implementation checks for one matching-radius cylindrical support,
+but does not establish complete correspondence between the recognized region,
+the imported host and its declared HostSize. A planar region labeled as a hole
+can currently pass this replacement path. An inconsistent HostSize can change the
+rebuilt host. These are known admission gaps; do not use this prototype as evidence
+that arbitrary imported geometry is preserved or that a replacement was verified.
+
+The canonical positive witness is
+`fixtures/Canonical/Integration/inline-step-recognize-replace.firmament`.
+It is a constrained integration fixture, not a general modeling recipe. See the
+[current audit](../../release/HOLE-RECOGNIZE-REPLACE-AUDIT-2026-10-20.md) for live
+reproduction and the proposed bounded next step. No broader capability is implied
+by proposal text or a replacement-ready metadata report.
diff --git a/docs/public/firmament/syntax.md b/docs/public/firmament/syntax.md
index 569fe676..5c7f4abd 100644
--- a/docs/public/firmament/syntax.md
+++ b/docs/public/firmament/syntax.md
@@ -373,8 +373,12 @@ volume.
mechanical compatibility syntax has the bounded lowercase
`region sideHole on face(+X) { cut Cylinder { ... } }` operation inside
`modify`; it is not a general native `Region` declaration. Prefer `Hole<Shaft>`
-for new hole construction. `Recognize` names a verified region of existing
-geometry. Sheet Metal's named planar regions and FEA's `Region:` selection
+for new hole construction. `Recognize` names an explicitly referenced region of
+imported geometry; its current binding checks are not automatic feature recognition
+or a complete geometric proof of the authored kind. The existing hole `Replace`
+lane is a bounded canonical box/through-hole rebuild, not general imported-body
+editing. See [imported feature recognition](imported-feature-recognition.md).
+Sheet Metal's named planar regions and FEA's `Region:` selection
fields are domain-owned uses of the word, with separate types and admission
rules. See [Sheet Metal](sheet-metal.md) and [FEA](fea.md).
diff --git a/docs/release/HOLE-RECOGNIZE-REPLACE-AUDIT-2026-10-20.md b/docs/release/HOLE-RECOGNIZE-REPLACE-AUDIT-2026-10-20.md
new file mode 100644
index 00000000..9ccf5c96
--- /dev/null
+++ b/docs/release/HOLE-RECOGNIZE-REPLACE-AUDIT-2026-10-20.md
@@ -0,0 +1,66 @@
+# Hole Recognize / Replace — current capability audit
+
+This was an assessment, not implementation of a new recognition or editing feature.
+Only documentation was changed. Source specimens, CLI JSON and STEP output are
+retained under ignored artifacts/local/hole-recognize-probes/ and
+artifacts/local/hole-recognize-current-*.
+
+## Verified current behavior
+
+- The canonical Integration/inline-step-recognize-replace.firmament source passes
+ validate and build. Export reports one planned/verified/emitted replacement,
+ holeShaft-bounded-rebuild, and residualSurgery=false.
+- The 54 FirmamentV2InlineStepTests pass against the current Release binaries.
+- Changing diameter from 2 mm to 3 mm rejects with
+ firmament-inline-step-replacement-verification-failed. This is not a qualified
+ imported-hole resize workflow.
+- Changing only the recognized Faces list from [7] to [1] still builds. Input
+ sequential face 1 is STEP #51 on a PLANE; face 7 is #191 on a
+ CYLINDRICAL_SURFACE of radius 1. The authored hole kind is not fully proved.
+- Changing HostSize from [10mm,8mm,6mm] to [20mm,8mm,6mm] still builds. Output
+ bounds are X=-10..10, Y=-4..4, Z=0..6. The imported host was 10 mm wide.
+ The report's verification does not establish host preservation.
+
+The probes use the same relative import path as the canonical fixture, from an
+artifact folder at the same depth. An initial attempt using an absolute InlineStep
+path was rejected by the existing path policy; those path errors were not treated
+as geometric capability evidence.
+
+## Ownership and root cause
+
+FirmamentV2Parser binds authored region kinds, face references and replacement
+parameters. FirmamentSemanticValues attaches exact BRep face/region bindings and
+imported entity provenance; it does not infer the complete manufacturing feature.
+
+FirmamentBuildAndExport.TryExportV2InlineStepReplacementBody is a bounded rebuild
+owner. It counts matching-radius cylindrical supports, creates a synthetic Box
+from HostSize, constructs a +Z through-hole with the existing shaft materializer,
+and exports that reconstructed body. Its volume check compares quantities derived
+from the rebuilt host; it does not independently prove equality to the import.
+It does not preserve arbitrary residual topology by surgery.
+
+The proposal assist is review-only metadata. Its replacementReady flag is not
+execution or geometric preservation proof. The older X4/X5/X7 reports describe
+this prototype and should not be read as a general imported-hole editing contract.
+
+## Suggested pre-launch slice
+
+1. Close false verification first: verify the selected faces and the entire admitted
+ host, derive host facts from the BRep, and reject inconsistent claims. Otherwise
+ disable replacement outside a genuinely proved reconstruction class.
+2. Recognize isolated analytic through-holes from actual imported BRep evidence:
+ cylindrical wall, axis/radius, boundary loops, concave material relationship,
+ compatible entry/exit supports and stable source associations. Explicitly reject
+ ambiguous split/partial/intersecting cases until admitted.
+3. Adopt a verified hole as named semantic geometry, attach PMI, and re-export
+ without changing geometry. This is distinct from replacing/rematerializing it.
+4. Permit regeneration/editing only for completely proved construction families
+ with independent geometry/correspondence qualification. Arbitrary imported-body
+ hole resizing, relocation, suppression or type conversion requires a separate
+ topology-editing milestone.
+
+No estimate in days is justified by this audit. Bounded recognition/adoption is a
+reasonable next capability; general imported topology editing is materially larger
+and should not be smuggled into launch polish. No full regression rerun was needed
+for this documentation-only assessment; the focused tests and real CLI paths above
+are the executed evidence, not a claim of new implementation qualification.