Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add inline STEP replacement assist reports

Yuechen Li7be12438816d
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.cs
index bceb0a4c..615b82d8 100644
--- a/Aetheris.CLI/CliRunner.cs
+++ b/Aetheris.CLI/CliRunner.cs
@@ -257,7 +257,8 @@ public static class CliRunner
success = true,
sourcePath = build.Value.SourcePath,
outputPath = build.Value.OutputPath,
- inlineStepMigration = build.Value.Export.InlineStepMigration
+ inlineStepMigration = build.Value.Export.InlineStepMigration,
+ inlineStepReplacementAssist = build.Value.Export.InlineStepReplacementAssist
}, JsonOptions));
}
else
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs
index 3cf82369..12feeff0 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentV2InlineStepTests.cs
@@ -200,6 +200,109 @@ model BadRecognitionProposal { units mm solid importedPart: InlineStep { path: "
Assert.Contains(diagnostic, parse.Diagnostics);
}
+
+
+ [Fact]
+ public void InlineStep_ReplacementAssist_ReadyHoleProposalProducesStableReplacementText()
+ {
+ var parse = ParseRecognizedHoleProposalFixture();
+ var report = InlineStepReplacementAssistReportBuilder.Build(parse.Document!);
+
+ Assert.Equal(1, report.ReadyCount);
+ Assert.Equal(0, report.BlockedCount);
+ var assist = Assert.Single(report.Assists);
+ Assert.True(assist.ReplacementReady);
+ Assert.Equal("holeShaft", assist.ProposalKind);
+ Assert.NotNull(assist.SuggestedReplacementModel);
+ Assert.Equal("replace importedPart.region(\"mountHole\") with hole<shaft> mountHole {" + Environment.NewLine +
+ " on: importedPart.face(\"#51\")" + Environment.NewLine +
+ " center: [0mm, 0mm]" + Environment.NewLine +
+ " radius: 1mm" + Environment.NewLine +
+ " end: throughAll" + Environment.NewLine +
+ "}", assist.SuggestedReplacementText);
+ Assert.Empty(parse.Document!.Replacements!);
+ }
+
+ [Theory]
+ [InlineData("datumPlane", "holeShaft", InlineStepReplacementAssistReportBuilder.RegionProposalKindMismatch)]
+ [InlineData("datumPlane", "datumPlane", InlineStepReplacementAssistReportBuilder.UnsupportedProposalKind)]
+ public void InlineStep_ReplacementAssist_BlocksKindIncompatibility(string regionKind, string proposalKind, string reason)
+ {
+ var document = ReplacementAssistDocument(regionKind: regionKind, proposalKind: proposalKind);
+ var assist = Assert.Single(InlineStepReplacementAssistReportBuilder.Build(document).Assists);
+ Assert.False(assist.ReplacementReady);
+ Assert.Contains(reason, assist.Reasons);
+ }
+
+ [Theory]
+ [InlineData(null, InlineStepReplacementAssistReportBuilder.MissingPlacementTarget)]
+ [InlineData("importedPart.face(\"#999999\")", InlineStepReplacementAssistReportBuilder.UnresolvedPlacementTarget)]
+ public void InlineStep_ReplacementAssist_BlocksMissingOrUnresolvedPlacementFace(string? target, string reason)
+ {
+ var document = ReplacementAssistDocument(placementTarget: target);
+ var assist = Assert.Single(InlineStepReplacementAssistReportBuilder.Build(document).Assists);
+ Assert.False(assist.ReplacementReady);
+ Assert.Contains(reason, assist.Reasons);
+ }
+
+ [Theory]
+ [InlineData(0d, InlineStepReplacementAssistReportBuilder.InvalidRadius)]
+ [InlineData(-1d, InlineStepReplacementAssistReportBuilder.InvalidRadius)]
+ public void InlineStep_ReplacementAssist_BlocksInvalidRadius(double radius, string reason)
+ {
+ var document = ReplacementAssistDocument(radius: radius);
+ var assist = Assert.Single(InlineStepReplacementAssistReportBuilder.Build(document).Assists);
+ Assert.False(assist.ReplacementReady);
+ Assert.Contains(reason, assist.Reasons);
+ }
+
+ [Fact]
+ public void InlineStep_ReplacementAssist_BlocksUnsupportedEndCondition()
+ {
+ var assist = Assert.Single(InlineStepReplacementAssistReportBuilder.Build(ReplacementAssistDocument(endCondition: "blind")).Assists);
+ Assert.False(assist.ReplacementReady);
+ Assert.Contains(InlineStepReplacementAssistReportBuilder.UnsupportedEndCondition, assist.Reasons);
+ }
+
+ [Theory]
+ [InlineData(false, "cylindrical", 1d, InlineStepReplacementAssistReportBuilder.EvidenceThroughFalse)]
+ [InlineData(true, "planar", 1d, InlineStepReplacementAssistReportBuilder.EvidenceSurfaceNotCylindrical)]
+ [InlineData(true, "cylindrical", 2d, InlineStepReplacementAssistReportBuilder.EvidenceRadiusMismatch)]
+ public void InlineStep_ReplacementAssist_BlocksEvidenceIncompatibility(bool through, string surfaceFamily, double evidenceRadius, string reason)
+ {
+ var document = ReplacementAssistDocument(evidenceThrough: through, surfaceFamily: surfaceFamily, evidenceRadius: evidenceRadius);
+ var assist = Assert.Single(InlineStepReplacementAssistReportBuilder.Build(document).Assists);
+ Assert.False(assist.ReplacementReady);
+ Assert.Contains(reason, assist.Reasons);
+ }
+
+ private static FirmamentV2ParseResult ParseRecognizedHoleProposalFixture()
+ {
+ var repo = FindRepoRoot();
+ var fixturePath = Path.Combine(repo, "fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-recognized-hole-proposal-report.valid.firmfixture");
+ var parse = FirmamentV2Parser.Parse(File.ReadAllText(fixturePath), Path.GetDirectoryName(fixturePath));
+ Assert.True(parse.IsSuccess, string.Join(Environment.NewLine, parse.Diagnostics));
+ return parse;
+ }
+
+ private static FirmamentV2Document ReplacementAssistDocument(
+ string regionKind = "holeShaft",
+ string proposalKind = "holeShaft",
+ string? placementTarget = "importedPart.face(\"#51\")",
+ double radius = 1d,
+ string endCondition = "throughAll",
+ bool evidenceThrough = true,
+ string surfaceFamily = "cylindrical",
+ double evidenceRadius = 1d)
+ {
+ var map = new ImportedStepTopologyMap(new Dictionary<string, string> { ["#51"] = "face-51", ["#191"] = "face-191" }, new Dictionary<string, string>());
+ var solid = new FirmamentV2SolidBinding("importedPart", "InlineStep", new FirmamentV2InlineStepRecord("canonical.step", "canonical.step", "hash", true, "canonical", map));
+ var evidence = new FirmamentV2RecognitionEvidence([surfaceFamily], evidenceRadius, "+Z", null, evidenceThrough);
+ var proposal = new FirmamentV2SemanticProposal(proposalKind, "mountHole", placementTarget, new FirmamentV2FaceLocalPoint2D(0d, 0d, FirmamentV2FaceLocalPoint2D.PlusZConvention), radius, endCondition);
+ var region = new FirmamentV2RecognizedRegion("importedPart", "mountHole", regionKind, ["#191"], "high", evidence, proposal);
+ return new FirmamentV2Document("AssistProbe", "mm", [solid], RecognizedRegions: [region], Replacements: []);
+ }
+
[Fact]
public void InlineStep_ReplacementDeclaration_ParsesAndReferencesRecognizedRegion()
{
diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
index 264ede0c..c1f1fedb 100644
--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
@@ -183,7 +183,8 @@ public static class FirmamentBuildAndExport
var step = Step242Exporter.ExportBody(materialized.Body, new Step242ExportOptions { ProductName = replacement.ReplacementFeatureName, ApplicationName = "Aetheris.Firmament.InlineStepReplacement" });
if (!step.IsSuccess) return KernelResult<FirmamentStepExportResult>.Failure(step.Diagnostics);
- return KernelResult<FirmamentStepExportResult>.Success(new FirmamentStepExportResult(step.Value, replacement.ReplacementFeatureName, 0, "inline-step-replacement", "holeShaft-bounded-rebuild", DatumInspection: [], DimensionInspection: [], InlineStepMigration: InlineStepMigrationReportBuilder.Build(document, solid, replacementsVerified: true, replacementsEmitted: true, emissionStrategy: "holeShaft-bounded-rebuild", residualSurgery: false)));
+ return KernelResult<FirmamentStepExportResult>.Success(new FirmamentStepExportResult(step.Value, replacement.ReplacementFeatureName, 0, "inline-step-replacement", "holeShaft-bounded-rebuild", DatumInspection: [], DimensionInspection: [], InlineStepMigration: InlineStepMigrationReportBuilder.Build(document, solid, replacementsVerified: true, replacementsEmitted: true, emissionStrategy: "holeShaft-bounded-rebuild", residualSurgery: false),
+ InlineStepReplacementAssist: InlineStepReplacementAssistReportBuilder.Build(document)));
}
private static double EstimateBoundingBoxVolume(BrepBody body)
@@ -232,7 +233,8 @@ public static class FirmamentBuildAndExport
"aetheris-canonical-ap242",
DatumInspection: [],
DimensionInspection: [],
- InlineStepMigration: InlineStepMigrationReportBuilder.Build(document, solid, emissionStrategy: "canonical-reexport", residualSurgery: false)));
+ InlineStepMigration: InlineStepMigrationReportBuilder.Build(document, solid, emissionStrategy: "canonical-reexport", residualSurgery: false),
+ InlineStepReplacementAssist: InlineStepReplacementAssistReportBuilder.Build(document)));
}
private static KernelResult<FirmamentStepExportResult>? TryExportV2ControlledSideHoleBody(FirmamentV2Document document)
diff --git a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
index 04c38986..fb4106e4 100644
--- a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
@@ -10,7 +10,8 @@ public sealed record FirmamentStepExportResult(
string ExportBodySelectionReason = FirmamentStepExporter.LastExecutedGeometricBodySelectionReason,
IReadOnlyList<FirmamentPmiInspectionDatum>? DatumInspection = null,
IReadOnlyList<FirmamentPmiInspectionDimension>? DimensionInspection = null,
- Aetheris.Kernel.Firmament.FirmamentV2.InlineStepMigrationReport? InlineStepMigration = null);
+ Aetheris.Kernel.Firmament.FirmamentV2.InlineStepMigrationReport? InlineStepMigration = null,
+ Aetheris.Kernel.Firmament.FirmamentV2.InlineStepReplacementAssistReport? InlineStepReplacementAssist = null);
public sealed record FirmamentPmiInspectionDatum(
string Label,
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/InlineStepMigrationReport.cs b/Aetheris.Kernel.Firmament/FirmamentV2/InlineStepMigrationReport.cs
index 12a06e2a..0ba94782 100644
--- a/Aetheris.Kernel.Firmament/FirmamentV2/InlineStepMigrationReport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/InlineStepMigrationReport.cs
@@ -15,7 +15,7 @@ public sealed record InlineStepMigrationReport(
IReadOnlyList<string> Diagnostics);
public sealed record InlineStepOriginalTopologyAccounting(int FaceCount, int EdgeCount, int VertexCount);
-public sealed record InlineStepRecognizedAccounting(int RegionCount, int ReferencedFaceCount, int DuplicateReferencedFaceCount, int UnresolvedReferenceCount, int EvidenceCount = 0, int ProposalCount = 0, int ProposalVerifiedCount = 0, int ProposalUnverifiedCount = 0);
+public sealed record InlineStepRecognizedAccounting(int RegionCount, int ReferencedFaceCount, int DuplicateReferencedFaceCount, int UnresolvedReferenceCount, int EvidenceCount = 0, int ProposalCount = 0, int ProposalVerifiedCount = 0, int ProposalUnverifiedCount = 0, int ProposalAssistReadyCount = 0, int ProposalAssistBlockedCount = 0);
public sealed record InlineStepReplacementAccounting(int PlannedCount, int VerifiedCount, int EmittedCount, int FailedCount, int ReplacedFaceCount);
public sealed record InlineStepResidualAccounting(int ResidualFaceCount, int UnclaimedFaceCount);
public sealed record InlineStepCoverageAccounting(double RecognizedFaceRatio, double ReplacedFaceRatio);
@@ -57,6 +57,7 @@ public static class InlineStepMigrationReportBuilder
}
}
+ var assist = InlineStepReplacementAssistReportBuilder.Build(document);
var replacements = (document.Replacements ?? []).Where(r => string.Equals(r.ImportedBodyName, solid.Name, StringComparison.Ordinal)).ToArray();
var replacedFaces = new HashSet<string>(StringComparer.Ordinal);
if (replacementsVerified)
@@ -86,7 +87,7 @@ public static class InlineStepMigrationReportBuilder
inlineStep.SourcePath,
inlineStep.ContentHash,
new InlineStepOriginalTopologyAccounting(originalFaceCount, 0, 0),
- new InlineStepRecognizedAccounting(regions.Length, uniqueRecognized.Count, duplicateCount, unresolvedCount, regions.Count(r => r.Evidence is not null), regions.Count(r => r.Proposal is not null), 0, regions.Count(r => r.Proposal is not null)),
+ new InlineStepRecognizedAccounting(regions.Length, uniqueRecognized.Count, duplicateCount, unresolvedCount, regions.Count(r => r.Evidence is not null), regions.Count(r => r.Proposal is not null), 0, regions.Count(r => r.Proposal is not null), assist.ReadyCount, assist.BlockedCount),
new InlineStepReplacementAccounting(plannedCount, verifiedCount, emittedCount, failedCount, replacedFaces.Count),
new InlineStepResidualAccounting(residualFaceCount, residualFaceCount),
new InlineStepCoverageAccounting(Ratio(uniqueRecognized.Count, originalFaceCount), Ratio(replacedFaces.Count, originalFaceCount)),
diff --git a/Aetheris.Kernel.Firmament/FirmamentV2/InlineStepReplacementAssistReport.cs b/Aetheris.Kernel.Firmament/FirmamentV2/InlineStepReplacementAssistReport.cs
new file mode 100644
index 00000000..03540c6b
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/FirmamentV2/InlineStepReplacementAssistReport.cs
@@ -0,0 +1,113 @@
+using System.Globalization;
+
+namespace Aetheris.Kernel.Firmament.FirmamentV2;
+
+public sealed record InlineStepReplacementAssistReport(
+ IReadOnlyList<FirmamentV2ReplacementAssistReport> Assists,
+ int ReadyCount,
+ int BlockedCount);
+
+public sealed record FirmamentV2ReplacementAssistReport(
+ string BodyName,
+ string RegionName,
+ string ProposalKind,
+ bool ReplacementReady,
+ string? SuggestedReplacementText,
+ FirmamentV2ReplacementAssistModel? SuggestedReplacementModel,
+ IReadOnlyList<string> Reasons,
+ IReadOnlyList<string> Diagnostics);
+
+public sealed record FirmamentV2ReplacementAssistModel(
+ string Target,
+ string ReplacementKind,
+ string FeatureName,
+ string PlacementTarget,
+ FirmamentV2FaceLocalPoint2D Center,
+ double Radius,
+ string EndCondition);
+
+public static class InlineStepReplacementAssistReportBuilder
+{
+ public const string UnsupportedProposalKind = "inline-step-replacement-assist-unsupported-proposal-kind";
+ public const string RegionProposalKindMismatch = "inline-step-replacement-assist-region-proposal-kind-mismatch";
+ public const string MissingPlacementTarget = "inline-step-replacement-assist-missing-placement-target";
+ public const string UnresolvedPlacementTarget = "inline-step-replacement-assist-unresolved-placement-target";
+ public const string InvalidRadius = "inline-step-replacement-assist-invalid-radius";
+ public const string UnsupportedEndCondition = "inline-step-replacement-assist-unsupported-end-condition";
+ public const string MissingCenter = "inline-step-replacement-assist-missing-center";
+ public const string EvidenceRadiusMismatch = "inline-step-replacement-assist-evidence-radius-mismatch";
+ public const string EvidenceThroughFalse = "inline-step-replacement-assist-evidence-through-false";
+ public const string EvidenceSurfaceNotCylindrical = "inline-step-replacement-assist-evidence-surface-not-cylindrical";
+
+ public static InlineStepReplacementAssistReport Build(FirmamentV2Document document)
+ {
+ ArgumentNullException.ThrowIfNull(document);
+ var assists = new List<FirmamentV2ReplacementAssistReport>();
+ foreach (var region in document.RecognizedRegions ?? [])
+ {
+ if (region.Proposal is null) continue;
+ assists.Add(BuildForRegion(document, region));
+ }
+ return new InlineStepReplacementAssistReport(assists, assists.Count(a => a.ReplacementReady), assists.Count(a => !a.ReplacementReady));
+ }
+
+ private static FirmamentV2ReplacementAssistReport BuildForRegion(FirmamentV2Document document, FirmamentV2RecognizedRegion region)
+ {
+ var proposal = region.Proposal!;
+ var reasons = new List<string>();
+ var diagnostics = new List<string>();
+ if (region.Kind != proposal.ProposalKind) reasons.Add(RegionProposalKindMismatch);
+ if (proposal.ProposalKind != "holeShaft") reasons.Add(UnsupportedProposalKind);
+ if (string.IsNullOrWhiteSpace(proposal.PlacementTarget)) reasons.Add(MissingPlacementTarget);
+ else if (!PlacementTargetResolves(document, proposal.PlacementTarget!)) reasons.Add(UnresolvedPlacementTarget);
+ if (proposal.Radius is not > 0d || double.IsNaN(proposal.Radius.Value) || double.IsInfinity(proposal.Radius.Value)) reasons.Add(InvalidRadius);
+ if (proposal.EndCondition != "throughAll") reasons.Add(UnsupportedEndCondition);
+ if (proposal.Center is null) reasons.Add(MissingCenter);
+ if (region.Evidence?.Through == false) reasons.Add(EvidenceThroughFalse);
+ if (region.Evidence?.SurfaceFamilies is { Count: > 0 } families && !families.Contains("cylindrical", StringComparer.Ordinal)) reasons.Add(EvidenceSurfaceNotCylindrical);
+ if (region.Evidence?.Radius is double evidenceRadius && proposal.Radius is double proposalRadius && Math.Abs(evidenceRadius - proposalRadius) > 1e-6) reasons.Add(EvidenceRadiusMismatch);
+
+ var ready = reasons.Count == 0;
+ FirmamentV2ReplacementAssistModel? model = null;
+ string? text = null;
+ if (ready)
+ {
+ model = new FirmamentV2ReplacementAssistModel(region.TargetSource, "holeShaft", proposal.FeatureName, proposal.PlacementTarget!, proposal.Center!, proposal.Radius!.Value, proposal.EndCondition!);
+ text = FormatReplacement(region, proposal);
+ }
+ else
+ {
+ diagnostics.Add("inline-step-replacement-assist-blocked");
+ }
+
+ return new FirmamentV2ReplacementAssistReport(region.BodyName, region.RegionName, proposal.ProposalKind, ready, text, model, reasons.Distinct(StringComparer.Ordinal).ToArray(), diagnostics.ToArray());
+ }
+
+ private static bool PlacementTargetResolves(FirmamentV2Document document, string target)
+ {
+ foreach (var solid in document.Solids)
+ {
+ if (solid.InlineStep is null) continue;
+ var prefix = solid.Name + ".face(\"";
+ if (target.StartsWith(prefix, StringComparison.Ordinal) && target.EndsWith("\")", StringComparison.Ordinal))
+ {
+ var entity = target[prefix.Length..^2];
+ return solid.InlineStep.TopologyMap.TryResolveFaceEntity(entity, out _);
+ }
+ }
+ return false;
+ }
+
+ private static string FormatReplacement(FirmamentV2RecognizedRegion region, FirmamentV2SemanticProposal proposal) =>
+ string.Join(Environment.NewLine,
+ [
+ $"replace {region.TargetSource} with hole<shaft> {proposal.FeatureName} {{",
+ $" on: {proposal.PlacementTarget}",
+ $" center: [{FormatMm(proposal.Center!.U)}, {FormatMm(proposal.Center.V)}]",
+ $" radius: {FormatMm(proposal.Radius!.Value)}",
+ " end: throughAll",
+ "}"
+ ]);
+
+ private static string FormatMm(double value) => value.ToString("0.##########", CultureInfo.InvariantCulture) + "mm";
+}
diff --git a/docs/implementation/inline-step-x6-recognition-evidence-proposals.md b/docs/implementation/inline-step-x6-recognition-evidence-proposals.md
index c8670f66..9eacbcb8 100644
--- a/docs/implementation/inline-step-x6-recognition-evidence-proposals.md
+++ b/docs/implementation/inline-step-x6-recognition-evidence-proposals.md
@@ -100,3 +100,8 @@ residualSurgery = false
- multiple proposals per region;
- edge/vertex evidence;
- counterbore/countersink/fillet/slot proposals.
+
+
+## Forward link
+
+INLINE-STEP-X7 adds review-only proposal-to-replacement assist for these X6 proposal records; see `docs/implementation/inline-step-x7-proposal-replacement-assist.md`.
diff --git a/docs/implementation/inline-step-x7-proposal-replacement-assist.md b/docs/implementation/inline-step-x7-proposal-replacement-assist.md
new file mode 100644
index 00000000..37a278c1
--- /dev/null
+++ b/docs/implementation/inline-step-x7-proposal-replacement-assist.md
@@ -0,0 +1,78 @@
+# INLINE-STEP-X7 proposal-to-replacement assist
+
+INLINE-STEP-X7 adds review-only proposal-to-replacement assist for Firmament V2 inline STEP recognized regions. It evaluates semantic proposals recorded on recognized regions and reports whether a proposal is compatible with the current explicit INLINE-STEP-X4 replacement path.
+
+The assist is not automatic replacement: it does not mutate geometry, create `replace` declarations, execute replacement, perform residual topology surgery, or claim full decompilation.
+
+## Supported proposal kind
+
+X7 supports exactly one proposal family:
+
+- recognized region kind: `hole<shaft>` / normalized `holeShaft`
+- proposal kind: `hole<shaft>` / normalized `holeShaft`
+- end condition: `throughAll`
+
+## Compatibility checks
+
+A proposal is replacement-ready only when:
+
+1. the recognized region has a semantic proposal;
+2. the recognized region kind matches the proposal kind;
+3. the proposal kind is `holeShaft`;
+4. the proposal placement target resolves to an imported STEP face;
+5. the proposal radius is positive and finite;
+6. the end condition is `throughAll`;
+7. center, radius, target, feature name, and end condition are enough to print X4 syntax;
+8. evidence radius matches proposal radius within `1e-6` when both are present;
+9. evidence `through: false` blocks `throughAll` assist;
+10. evidence surface families must include `cylindrical` when supplied.
+
+The current assist intentionally stays at metadata/topology-reference level; broader geometric proof and multi-proposal scoring are deferred.
+
+## Report model and build JSON
+
+`InlineStepReplacementAssistReport` contains `assists`, `readyCount`, and `blockedCount`. Each assist records `bodyName`, `regionName`, `proposalKind`, `replacementReady`, optional `suggestedReplacementText`, optional `suggestedReplacementModel`, deterministic `reasons`, and `diagnostics`.
+
+`aetheris build --json` now includes `inlineStepReplacementAssist` next to `inlineStepMigration`. The migration recognized accounting also exposes `proposalAssistReadyCount` and `proposalAssistBlockedCount`; these are separate from replacement planned/verified/emitted counts.
+
+## Suggested replacement text
+
+Ready assists produce stable X4-compatible text:
+
+```firmament
+replace importedPart.region("mountHole") with hole<shaft> mountHole {
+ on: importedPart.face("#51")
+ center: [0mm, 0mm]
+ radius: 1mm
+ end: throughAll
+}
+```
+
+This text is review support only. The source document remains recognized/proposed-only unless a human adds an explicit `replace` declaration.
+
+## Fixture and geometry proof
+
+The primary fixture is:
+
+```text
+fixtures/FirmamentV2/InlineStep/valid/inline-step-v2-recognized-hole-proposal-report.valid.firmfixture
+```
+
+For that fixture, build JSON reports one ready assist and zero blocked assists, while replacement planned/verified/emitted counts remain zero. The emitted STEP remains the canonical inline STEP re-export; AP242 analyze volume remains `461.15044407846125`, proving the assist did not mutate geometry.
+
+The X4 replacement fixture remains the regression for actual replacement execution and bounded rebuild verification.
+
+## Relationship to X4
+
+X4 defines the explicit bounded replacement syntax and execution path. X7 only determines whether a recognized-region proposal has enough compatible metadata to suggest that syntax. Replacement authority still comes only from an explicit `replace` declaration.
+
+## Deferred features
+
+- automatic replacement;
+- multi-proposal ranking;
+- JudgmentEngine scoring;
+- counterbore, countersink, fillet, slot, and pocket proposals;
+- true residual surgery;
+- raw vendor STEP inline support;
+- graphical PMI and frontend changes;
+- Forge concept registry integration.