EPIC: SQL/MM Spatial (ISO/IEC 13249-3) Curve Awareness in JTS

[grootstebozewolf]

Epic: Curve and Extended-Geometry Awareness in JTS (OGC SFA + ISO 13249-3 SQL/MM)

AI Disclosure (per the Eclipse Foundation Generative AI Usage Guidelines for Committers)

This document was largely AI-generated. The human contributor has reviewed and
verified the technical content (cross-module impact, risk register, phase
dependencies, TAG scope) for correctness. The AI-generated portions are made
available under CC0-1.0 (public domain dedication) and are not subject to
the project's licence; human curation and edits are subject to the JTS dual licence.

SPDX-License-Identifier: (EPL-2.0 OR EDL-1.0) AND CC0-1.0
Assisted-by: xAI Grok (grok-4.3)
Assisted-by: Claude (Opus-4.8)

Status: Draft v4 (standard PR-tracked).
Source branch: feature/sfa-curve-buffer-spike on grootstebozewolf/jts.
Audience: locationtech/jts maintainers and contributors.

1. Goal

Make JTS preserve curved and extended geometry types — CIRCULARSTRING, COMPOUNDCURVE, CURVEPOLYGON, MULTICURVE, MULTISURFACE, TRIANGLE — through every algorithm where the math is sound, instead of silently linearising to flat parents on the way in.

Standards provenance. OGC Simple Feature Access (ISO 19125-1) defines a geometry model with linear interpolation between vertices. Of the types above, SFA 1.2.1 (OGC 06-103r4) defines only the abstract MULTICURVE / MULTISURFACE supertypes and the TRIANGLE surface; the concrete curved types — CIRCULARSTRING, COMPOUNDCURVE, CURVEPOLYGON — and circular interpolation come from ISO/IEC 13249-3 (SQL/MM Spatial), not from SFA. (In OGC 06-103r4 those curved type names appear only in a type-code table that explicitly notes the entries "are for future use and do not reflect types used here.") ISO 19125-2 is the SQL-bindings part of SFA and introduces no curve types, so it is not the source of curve awareness and should not be cited as such.

Today jts-curved is past the parse-only stand-in: the structural composites and several analytical properties already land arc-aware (see §5 table). This epic tracks the remaining lift, operation by operation.

2. Why

• Performance. Each densification step expands one arc into a chord polyline — about 12 chords (13 vertices) for a half-circle at the default 1% chord-error (sagitta) tolerance, rising to ~36 at 0.1%; pipelines that buffer → simplify → union compound the cost.
• Precision. Densify → operate → densify drifts control points by ULPs and breaks snap-to-grid round-trips against external SFA producers.
• Interop. PostGIS, Oracle Spatial, NetTopologySuite emit and consume curve geometries; today JTS round-trips them as visibly different shapes after every operation.
• Discoverability. TestBuilder cannot show a curved buffer or a curved boundary today; users of the spec types never see what their input was for.

3. Scope decisions

In scope (this epic):

• Algorithms operating on the six curved / extended geometry types in 2-D.
• WKT round-trip with member structure.
• TestBuilder rendering and drawing tools.

Deferred to sibling epics — explicitly tracked, not pretended-not-to-exist:

• WKB curve-aware extensions (extended geometry-type codes 1000-series). PostGIS interop runs on WKB, so the interop benefit listed in §2 is incomplete without it. Not blocking the algorithm work. Action: open a child issue "WKB curve types" before this epic ships.
• 3-D solids (POLYHEDRALSURFACE, TIN). Their structural / drawing support landed for visualisation; no 3-D semantics here.
• Elliptic arcs (ELLIPSARC) — JTS has no ellipse model; adding one is bigger than this epic.
• Z / M ordinate interpolation across densified arcs.

4. How we work (the standard model)

This epic is large, but we deliberately do not fragment it into dozens of issues, and we do not keep a meta progress fixture in the test tree. Instead:

1. One TAG, one self-contained PR. Each TAG in the §5 table is shipped by a single PR (or a tightly-coupled cluster) that stands on its own: it compiles, its tests pass, and a reviewer can understand it without reconstructing the rest of the epic. Brain-friendly for a solo maintainer — small enough to review in one sitting.
2. A PR is a feature, a fix, an arch change, or a spec. Use the bucket prefix and the TAG in the commit subject + PR title:

   feat: BUF-1 analytical single-arc CircularString buffer → CurvePolygon
   

   Buckets: feat:, fix:, arch:, test:, spec:, refactor:.
3. The §5 table is the live status. Each TAG row carries its PR link (or — if none yet) and a status. That is the progress meter — standard GitHub PR state, nothing bespoke.
4. The §6 changelog is updated every time a PR lands for review. When a PR opens against dr-jts, add one log entry (newest first). The entry reads like a book — a short narrative a reviewer can read top-to-bottom — and for a feat: it links exactly two files: the source that implements it and the test that proves it (open-in-Codespace blob links). Fixes/arch/spec entries link whatever is relevant.
5. CI is green by default. There is no excluded "intentionally red" suite. Every test in the tree passes; coverage for a TAG arrives as ordinary green tests in the same PR.

5. TAG status

Status legend: ✅ merged to locationtech/jts · 🔵 PR open for review · 🟢 implemented on fork (PR pending) · ⬜ planned · ✩ stretch.

PR numbers below are filled where known; — means no PR has been opened yet. Maintainer/contributor: update the PR + status cells as PRs land (this is the single source of truth that replaces the old red-test count).

Phase 1 — Foundations (jts-curved structural completeness)

TAG	What	PR	Status
F-CP	Structural CurvePolygon — curve shell + holes; copyInternal/reverseInternal/toLinear/WKT preserve structure	#1198	🔵
F-MC	Structural MultiCurve — preserves member subtypes	#1198	🔵
F-MS	Structural MultiSurface — preserves Polygon vs CurvePolygon members	#1198	🔵
(base)	SFA/ISO extension hooks + opt-in jts-curved module	#1194	🔵
F-RD	CurvedShapeWriter arc-renders CurvePolygon rings + MultiCurve/MultiSurface members	—	⬜

Phase 2 — Properties (Metrics, Boundary, Validity)

TAG	What	PR	Status
M-LEN-CS	Analytical CircularString length (r·θ)	—	🟢
M-LEN-CC	CompoundCurve length sums member lengths	—	🟢
M-AREA-CP	CurvePolygon area (Green's theorem + circular-segment correction)	—	🟢
M-DIM	Empty-curve dimension / coordinate-dimension guards	—	⬜
B-CP	CurvePolygon.getBoundary() returns a curve (CompoundCurve / MultiCurve)	—	🟢
B-MS	MultiSurface.getBoundary() returns a MultiCurve	—	🟢
B-CC	Open CompoundCurve boundary = its two endpoints; closed = empty	—	⬜
V-CP	CurvePolygon validity (arc self-intersection, sector orientation, holes-in-shell)	—	⬜
V-CS	CircularString / CompoundCurve simplicity	—	⬜

Phase 3 — Measurement (Distance, Centroid, Interior point)

TAG	What	PR	Status
D-PT	Analytical point-to-arc distance (clamped to sweep)	—	🟢
D-AA	Analytical arc-to-arc distance	—	⬜
D-OP	DistanceOp accepts curved inputs without forced densification	—	⬜
D-HF	DiscreteHausdorffDistance / DiscreteFrechetDistance parameterised by arc length	—	⬜
C-LIN	CircularString centroid (arc-length-weighted)	—	🟢
C-AREA	CurvePolygon area centroid (Green's-theorem moments)	—	🟢
C-IP	CurvePolygon interior point (arc-aware scan line)	—	🟢

Phase 4 — Construction (Buffer, Hulls, Simplification, Affine, Linear-Ref, Densifier)

TAG	What	PR	Status
BUF-1	Analytical single-arc buffer → CurvePolygon	—	⬜
BUF-N	Multi-arc / mixed CompoundCurve buffer preserves arcs	—	⬜
BUF-NEG	Negative buffer with |d| > R returns EMPTY cleanly	—	⬜
OFF	OffsetCurve preserves arc identity (R±d)	—	⬜
VBF	VariableBuffer interpolates along arc length	—	⬜
H-CV	Convex hull uses arc extreme points	—	⬜
H-CC	Concave hull arc-aware	—	⬜
S-DP	DouglasPeuckerSimplifier preserves arc identity	—	⬜
S-VW	VWSimplifier arc-aware	—	⬜
S-TP	TopologyPreservingSimplifier arc-aware	—	⬜
AT-S	Similarity affine transform preserves arc	—	⬜
AT-NS	Non-similarity affine densifies cleanly (see §7)	—	⬜
LRF-LEN	LengthIndexedLine parameterised by arc length	—	⬜
LRF-LOC	LocationIndexedLine member-aware on CompoundCurve	—	⬜
DSF	Densifier delegates to toLinear for arc input	—	⬜

Phase 5 — Noding foundation (touches jts-core — see §8)

TAG	What	PR	Status
N-AA	Public arc-arc intersection utility	—	⬜
N-AL	Public arc-line intersection utility	—	⬜
N-SS	Arc-aware SegmentString / Noder integration	—	⬜

Phase 6 — Overlay, Predicates, Polygonizer, Coverage (depends on Phase 5)

TAG	What	PR	Status
OV	Arc-preserving overlay output (union / intersection / difference / symDifference)	—	⬜
R-PR	Arc-aware relate matrix	—	⬜
R-CONT	Arc-aware contains / intersects / covers / within / touches / crosses	—	⬜
R-EQ	equalsExact distinguishes arc from chord polyline	—	⬜
PLG	Polygonizer accepts CompoundCurve edges, emits CurvePolygon faces	—	⬜
COV	CoverageUnion preserves shared arc edges	—	⬜

Phase 7 — Independent tracks (depend only on Phase 1)

TAG	What	PR	Status
PRC-SN	Snap-to-grid preserves arc when snapped (R, centre, sweep) stays on grid	—	⬜
TRI-DT	DelaunayTriangulationBuilder accepts curved input (densify internally)	—	⬜
TRI-VR	VoronoiDiagramBuilder accepts curved input	—	⬜
TB-T	CompoundCurveTool / CurvePolygonTool drawing UX	—	⬜
TB-FN	Function-tree curve-awareness badges (●/◯/✕)	—	✩

6. Changelog (newest first)

One entry per PR that lands for review. Read like a book. A feat: entry links exactly two files — src (what implements it) and test (what proves it) — as open-in-Codespace blob links. Append, never rewrite history.

feat: F-CP / F-MC / F-MS — structural composites — #1198

CurvePolygon stops throwing its rings away on the way in. It now keeps the structural shell and holes (CircularString / CompoundCurve / LineString) and exposes them through new getExteriorCurve() / getInteriorCurveN(int), while the inherited getExteriorRing() keeps returning a densified LinearRing view so existing Polygon callers and all of jts-core keep working unchanged (Option A from SPEC_F_CP.md). MultiCurve and MultiSurface gain the same subtype-preserving treatment, and the CurvedWKTReader / CurvedWKTWriter round-trip the ring structure (CIRCULARSTRING / COMPOUNDCURVE tags inside the CURVEPOLYGON body). copyInternal, reverseInternal, toLinear, and normalize all carry the curves through.

• src: CurvePolygon.java
• test: CurvePolygonStructuralSpec.java

arch: (base) — SFA / ISO 19125-2 extension hooks + opt-in jts-curved — #1194

Adds the seams the rest of the epic hangs off: WKTReader.readOtherGeometryText and WKTWriter.appendOtherGeometryTaggedText extension points (plus a handful of helpers promoted to protected), the canonical type-keyword constants, and the opt-in jts-curved module with the extended geometry types and their CurvedWKTReader / CurvedWKTWriter. No behaviour change for existing core callers.

• src: WKTReader.java · CurvedWKTReader.java
• test: WKTReaderExtensionHookTest.java

7. Risks / open questions

• Backwards compatibility on structural composites. Algorithms that don't recognise a curve subtype today silently densify. With structural CurvePolygon, a third-party algorithm that expects a LinearRing shell may break. Option A (landed in feat: F-CP structural CurvePolygon (Option A) + enable F-MC/F-MS #1198) keeps the inherited getExteriorRing() returning a densified LinearRing view, so old code keeps limping; curve-aware code uses getExteriorCurve().
• equalsExact semantic change (R-EQ). Today CIRCULARSTRING(p0,p1,p2).equalsExact(LINESTRING(p0,p1,p2)) returns true via shared coordinates. Making it false is per spec, but it's a behaviour change for any user comparing-by-WKT-text. Needs a release note.
• Non-similarity affine (AT-NS). Sheared arcs are ellipse arcs, which JTS doesn't model. Plan is detect-and-densify; decide what getGeometryType() returns on the result before AT-NS lands.
• Performance of public arc-arc / arc-line intersection (N-AA, N-AL). The two-circle solve is fine for low cardinality; indexing of arc spans (bounding-box pruning) is non-trivial. Benchmark before committing to a design.
• Z / M propagation across densified arcs. Every TAG that produces densified output (DSF, AT-NS, …) should choose a Z/M policy that doesn't lock out a proper interpolation later. (toLinear interpolates Z linearly along the sweep as of the F-CP densification work.)

8. Cross-module impact

Most TAGs ship purely inside jts-curved (extension module, opt-in). A handful require touching jts-core and need a maintainer review up-front:

TAG group	jts-core change?	Notes
F-RD	Possibly	Only if ShapeWriter needs new extension hooks for CurvePolygon rings.
N-AA, N-AL, N-SS	Yes	SegmentString / Noder hierarchy lives in core. Largest core surface in the epic.
OV	Indirect	Depends on N-SS; overlay pipeline itself stays in core.
R-PR, R-CONT	Indirect	RelateOp lives in core; if N-SS is the seam, no further core change needed.
PLG	Yes	Polygonizer lives in core; needs to accept CompoundCurve edges.
PRC-SN	Yes	PrecisionModel.makePrecise integration.
DSF	Yes (or shadow)	Densifier lives in core; alternative is to wrap and shadow it from jts-curved.

Everything else is jts-curved-only or jts-app (TestBuilder).

9. Phases & suggested order

Phase 1 (Foundations)
   │
   ├──> Phase 2 (Properties)
   ├──> Phase 3 (Measurement)
   ├──> Phase 4 (Construction)
   ├──> Phase 5 (Noding)  ──>  Phase 6 (Overlay / Predicates / Polygonizer)
   └──> Phase 7 (Independent tracks: snap / triangulation / TestBuilder)

Phase 1 is the hard prerequisite for everything (you can't return a CompoundCurve boundary of a CurvePolygon whose ring isn't a CompoundCurve to begin with). After Phase 1, Phases 2 / 3 / 4 / 5 / 7 can run in parallel; Phase 6 waits for Phase 5.

10. Definition of Done (epic-level)

The epic closes when all of:

1. Every TAG in §5 is ✅ (merged) — or explicitly de-scoped in the table with a one-line reason.
2. The 6 curve types round-trip through every public Geometry operation in the user guide without producing flat output where curve-preserving output is mathematically possible.
3. The deferred WKB sibling epic has its own tracking issue.
4. A release note covers the equalsExact change (§7) and any other user-visible behaviour shifts.

TB-FN (function-tree badges) is a stretch goal, not a DoD criterion.

11. Conventions

• TAGs are short, unique, and stable.
• One TAG per PR (or a tightly-coupled cluster). The PR is self-contained, green, and reviewable in one sitting.
• The PR updates the §5 table (PR link + status) and prepends a §6 changelog entry.
• CI stays green — no excluded suites.

12. References

• OGC Simple Feature Access 1.2.1 (OGC 06-103r4) / ISO 19125-1 — linear geometry model; abstract MultiCurve / MultiSurface, and Triangle.
• ISO/IEC 13249-3 (SQL/MM Spatial) — circular interpolation and the CircularString / CompoundCurve / CurvePolygon curved types.
• jts-curved source: modules/curved/.
• F-CP design note: modules/curved/SPEC_F_CP.md.
• Spike branch: feature/sfa-curve-buffer-spike on grootstebozewolf/jts.

[grootstebozewolf]

Focused spike landed on the fork for one TAG: F-CP — Structural CurvePolygon. Branch: feature/sfa-curve-F-CP-spike (single commit, spike-only, no production-code change yet).

Why F-CP first

Walking the 49 TAGs against the §6 cross-module table, §7 risk register, and the §10 phase graph, F-CP stands out:

• Critical path. Hard Phase-1 prereq for every Phase-2 TAG that needs to talk about a curved boundary, area, or validity (B-CP, M-AREA-CP, V-CP). Phase 2 can't ship until F-CP does.
• §7 risk Deleted unsupported modules: jts-jump, libjts, jts-sde-adapter. #1 lives here. Polygon.getExteriorRing() is typed LinearRing; a structural CurvePolygon's actual shell is a CompoundCurve. Those two facts can't both be true at runtime — the dovetail choice has to be made before the implementation PR, not inside its review.
• Already interacts with shipping code. PR #1194 ships a Phase-1 stand-in that silently linearises CurvePolygon rings on read. Any future structural form has to coexist with or replace that path.
• Precondition met. The feature/sfa-curve-compoundcurve-members branch on the fork (commit 29723a30) restructures CompoundCurve to store LineString[] members with getCurveN(int) / getNumCurves(). F-CP picks up from there — the spike's helpers already bridge to that API by reflection so the red tests compile against the current extension-points head.

What's on the spike

• CurvePolygonStructuralSpec.java — 8 red tests covering 7 F-CP sub-TAGs (FCP-S / FCP-MEM / FCP-H / FCP-CP / FCP-TL / FCP-WKT / FCP-DOVE), each fail() naming its sub-TAG so the message stream stays a live progress meter for the F-CP sub-surface, mirroring the role of CurveAwarenessSpecTest at the epic level.
• SPEC_F_CP.md — captures the FCP-DOVE branching table with trade-offs, where we lean, and what's deferred.
• modules/curved/pom.xml — adds the Surefire exclude **/spec/curveawareness/*.java per §11 so the spike's red tests don't redden default CI. On-demand: mvn -pl modules/curved test -Dtest=CurvePolygonStructuralSpec.

Posture verified: default reactor build BUILD SUCCESS with checkstyle (55 jts-curved tests green); explicit spec run yields 8 failed / 8 run with TAG-tagged messages.

The dovetail decision (FCP-DOVE)

Three live options for what Polygon.getExteriorRing() returns on a structural CurvePolygon:

Option	getExteriorRing()	New accessor	Trade-off summary
A — legacy fallback	LinearRing of densified chord coords at a default tolerance	getExteriorCurve() returns the structural Curve	Two-tier API; old callers keep working but see a polyline approximation. Lowest friction for jts-core.
B — widen return type	LineString (CompoundCurve extends LineString)	none — existing method suffices	Single source of truth, no API doubling. Breaks every caller that does (LinearRing) p.getExteriorRing() — needs a core-wide audit.
C — fail-fast	throws UnsupportedOperationException	getExteriorCurve() returns the structural Curve	Loudest diagnostic; forces every caller to migrate. Probably only acceptable behind a feature flag.

We lean A today (lowest blast radius on jts-core, two-tier API as the deliberate cost). B becomes attractive again if the number of (LinearRing) casts on getExteriorRing() results inside jts-core turns out to be small — that count is the deciding number. Full trade-offs and what's deferred (default tolerance, getCoordinates() policy, hole symmetry) are in SPEC_F_CP.md.

Smallest concrete next step

A one-line A / B / C reply from a maintainer on this issue. After that:

1. An arch: commit on the spike branch deletes the unselected rows from SPEC_F_CP.md to record the decision.
2. A separate implementation PR starts from there: updates to CurvePolygon, CurvedGeometryFactory, CurvedWKTReader.readCurvePolygonText, CurvedWKTWriter, and deletes the now-green methods in CurvePolygonStructuralSpec per the §5 convention.

The door is deliberately left open — if a Phase-2 TAG surfaces a constraint we missed before the implementation PR lands, revisiting the option is fair game. Post-merge it becomes a breaking change.

---

Assisted-by: Claude (Opus-4.7)

[grootstebozewolf]

F-CP / FCP-DOVE — three option spikes ran; B and C ruled out

Per the request to continue the spike until each option is ruled out or surfaces benchmarks, ran a branch per option. All three spikes are now on the fork; B and C produce strong rule-out evidence, A flips half the F-CP red tests green and exposes only secondary design questions that are implementation-PR scope.

Branches

Option	Branch	Build	F-CP reds
A — legacy fallback (getExteriorCurve() + legacy getExteriorRing())	feature/sfa-curve-F-CP-spike-optionA	BUILD SUCCESS, 55/55 Phase-1 tests green	4 of 8 flip green
B — widen Polygon.getExteriorRing() return type to LineString	feature/sfa-curve-F-CP-spike-optionB	intentionally non-compiling	n/a
C — fail-fast on getExteriorRing()	feature/sfa-curve-F-CP-spike-optionC	compiles, but 2 existing curved tests regress	not measured (probe instead)

Cast survey first

Across modules/core/src/main/java:

Pattern	Count
getExteriorRing() call sites	57
getInteriorRingN() call sites	47
explicit (LinearRing) casts on either result	10

The 10-cast number is what the spec doc bet B on. The real measurement (below) is much larger.

Option A — feasible, minimal, no regressions

Diff: +60 / −8 across CurvePolygon, CurvedWKTReader, and the spike helpers. Adds a new field LineString structuralShell, a new constructor that derives the legacy LinearRing shell via Linearizable.toLinear(0.0), a new getExteriorCurve() accessor, and updates copyInternal() to preserve the structural shell.

Test posture on the A branch:

• 55/55 jts-curved Phase-1 tests stay green — no regressions
• 4 of 8 FCP red tests flip green: FCP-S (compound shell), FCP-S (single-arc), FCP-CP (copy preservation), FCP-DOVE (the design-decision marker)
• 4 reds remain — but each tracks an independent sub-TAG that A/B/C all share equally:
  • FCP-MEM waits on feature/sfa-curve-compoundcurve-members
  • FCP-H is the parallel getInteriorCurveN(int) accessor (cosmetic)
  • FCP-WKT is a writer-side TAG (separate sub-issue)
  • FCP-TL waits on feature/sfa-curve-toLinear-densification

One open question A defers to the implementation PR: the default tolerance source for the linearised getExteriorRing() view. Today's toLinear(0.0) ignores the tolerance argument; a real implementation parameterises on PrecisionModel scale or a CurvedGeometryFactory field. Not an A-vs-B-vs-C decision.

Option B — RULE-OUT for Phase 1

Two-method widening of Polygon from LinearRing to LineString (the entire mechanical surface of B). Then mvn -pl modules/core compile:

Metric	Count
Compile errors in jts-core/main	108
Distinct files affected	25
Highest-impact file	operation/valid/IsValidOp.java (12 errors)
Files with 4+ errors	19 of 25

The original 10-cast number undercounted by 10×. The compiler also flags every implicit assignment (LinearRing r = polygon.getExteriorRing() with no cast) and every pass-through into new Polygon(LinearRing, ...). Full breakdown in NOTE_OPTION_B.md and the raw mvn error log preserved at SPIKE_OPTION_B_compile_errors.txt.

Beyond the 108 sites, B fails the "single source of truth" sales pitch: the Polygon constructor still takes LinearRing shell, LinearRing[] holes, so most of the 108 fix sites end up adding explicit (LinearRing) casts to satisfy the constructor — recreating the two-tier API Option A would have made explicit. And the API change is binary-incompatible for every downstream consumer (PostGIS-Java, GeoTools, etc.).

Verdict for Phase 1: no. B remains viable as a post-A deprecation cycle — widen the API, keep the LinearRing-returning method as a deprecated shim, do the 108-site sweep over multiple PRs.

Option C — RULE-OUT, including as a feature flag

Override getExteriorRing() and getInteriorRingN(int) on CurvePolygon to throw UnsupportedOperationException; route internal copyInternal() / toLinear() via super.* calls.

Blast-radius probe (OptionCBlastRadiusProbe.java) pipes a CURVEPOLYGON(CIRCULARSTRING(0 0, 10 0, 5 5, 0 5, 0 0)) through 32 representative jts-core operations:

total: 32   ok: 16   UOE: 16   other-error: 0

50 % blast radius. What survives: methods that read Polygon's internal shell field directly (getCoordinates, getArea, getLength, getBoundary, copy, normalize, isSimple, plus all geometry-metadata). What breaks: every relational predicate (intersects / contains / intersection / union / difference / distance), buffer, getCentroid, getInteriorPoint, convexHull, reverse, isValid, toText, and the curve-aware CurvedWKTWriter.write() itself.

Empirical confirmation in the unchanged Phase-1 suite: two existing curved-module tests break under Option C without any test-code edit — WKTCurvePolygonTest.testWKTRoundTripXY and WKTMultiSurfaceTest.testWKTRoundTripXY, both via CurvedWKTWriter → appendPolygonText → getExteriorRing() → UOE.

A feature-flagged C reduces to "A with an optional explosion mode" because the flag-off behaviour has to be either A or B. Verdict: rule out as the default contract. C survives as a useful idea in a smaller scope: a CurvedGeometryFactory diagnostic-mode wrapper that strict pipelines opt into to confirm no non-curve-aware code touches their CurvePolygons. That's a separate, smaller feature.

Recommendation

Land F-CP under Option A. A is the only option that ships without a sweeping core PR or a 50% method-availability hole, and the spike shows it's a ~60-LOC additive change with no regressions.

The implementation PR's remaining open questions (default linearisation tolerance, getCoordinates() policy, hole-symmetry timing) are all scoped to A's implementation, not to the A-vs-B-vs-C choice.

If maintainers want to keep B alive as a future cleanup, the right shape is "A now, B-style widening in a follow-up release with a deprecation cycle" — captured at the bottom of NOTE_OPTION_B.md.

The door's still open if a Phase-2 TAG surfaces a constraint that changes the trade-off before the F-CP implementation PR lands.

---

Assisted-by: Claude (Opus-4.7)

[grootstebozewolf]

Continuing — F-MC + F-MS Phase-1 finish, AT-NS §7-risk-#3 spike

Two more workflow loops on the fork:

TAG group	Branch	Status
F-MC + F-MS (composite-member preservation)	feature/sfa-curve-F-MC-F-MS-spike	Phase-1 reader half already free, writer half closed
AT-NS (affine on curved geometry, §7 risk #3)	feature/sfa-curve-AT-NS-spike	three-option spec + probe; lean Option A

F-MC + F-MS — half-already-free, half-closed

Wrote a 6-test red spec and ran it against the PR-1194 base before touching code. Four of six green on the unchanged base:

• FMC-READ, FMC-COPY — MultiCurve preserves CircularString / CompoundCurve member subtypes via CurvedWKTReader.readCurveMember's dispatch through readGeometryTaggedText; MultiLineString.copy() propagates each member's runtime class through copyInternal() without F-CP-style storage redesign.
• FMS-READ, FMS-COPY — same shape for MultiSurface holding plain Polygon + CurvePolygon members.

The two reds were both writer-side: MULTICURVE and MULTISURFACE round-tripped through CurvedWKTWriter.write() came back as flat polylines/polygons because WKTWriter.appendMultiLineStringText / appendMultiPolygonText emit per-member body-only bodies, dropping the type tag.

Fix: ~75 LOC additive on CurvedWKTWriter, overriding the appendOtherGeometryTaggedText hook from PR #1194 to intercept MultiCurve and MultiSurface. Per-member emission emits body-only (x y, …) for plain LineString / Polygon members and tagged CIRCULARSTRING (…) / COMPOUNDCURVE (…) / CURVEPOLYGON (…) for curve members. No jts-core change — the extension hook already in place handles the seam.

Posture: default mvn -pl modules/curved test is 55/55 green, on-demand spec is 6/6 green, full reactor with checkstyle is BUILD SUCCESS.

Phase-1 status after this branch:

TAG	State
F-CP	pending — Option A recommended in earlier comment
F-MC	reader done on base; writer closed by this spike
F-MS	reader done on base; writer closed by this spike
F-RD	TestBuilder rendering — separate Phase 4-B / lab work

Once F-CP lands under Option A, Phase 1 is structurally complete and Phases 2/3/4/5/7 unlock per the §10 graph.

AT-NS — §7 risk #3 with branching table + probe

Followed the same shape as FCP-DOVE: a SPEC_AT_NS.md with a three-option branching table, an 8-test red spec pinned to the lean option, and a current-behaviour probe so the measurement is reproducible.

Branching table

Option	Non-similarity behaviour	getGeometryType()	Trade-off
A — silent densify	densify via toLinear(tolerance), then transform the polyline	result is LineString	Geometrically faithful; type changes silently. Matches §7's "detect-and-densify".
B — preserve type, accept drift (today)	transform the 3 control points; the new arc is the circle through transformed points	CircularString (lies)	Type stable; geometrically wrong for shears / non-uniform scales.
C — fail-fast	detect non-similarity, throw UnsupportedOperationException	n/a	Loudest diagnostic. Probably only acceptable behind a strict-mode flag.

Probe output, today

transform                  similarity?  out-type        out-pts  control-pts-on-circle?
identity                   true         CircularString  3        true
translate(10, 20)          true         CircularString  3        true
scale(2, 2) uniform        true         CircularString  3        true
rotate(pi/4)               true         CircularString  3        true
reflect x-axis             true         CircularString  3        true
scale(2, 1) non-uniform    false        CircularString  3        true   <-- LIES
scale(3, 1) non-uniform    false        CircularString  3        true   <-- LIES
shear-x 0.5                false        CircularString  3        true   <-- LIES

The probe carries a static isSimilarity(AffineTransformation) helper using the standard linear-algebra test (a² + c² == b² + d² and ab + cd == 0). It correctly flags every non-similarity, but apply(...) still returns a CircularString — Option B in action. The "on-circle" column is the geometric sanity check: 3 distinct non-collinear points always lie on some circle, so the result is a valid CircularString syntactically even when it has nothing to do with the elliptical image of the original arc.

Where we lean

Option A. Three reasons in SPEC_AT_NS.md:

1. It is the only option where the result is a faithful representation of the affine image of the original arc. B's result is a different geometric curve entirely; C avoids the question.
2. The type change is observable and recoverable: a curve-aware caller can branch on g.getGeometryType() after the call.
3. A drops in cleanly with the existing Linearizable contract; the non-similarity branch becomes one call to toLinear(tolerance) followed by transforming the linearised result. The toLinear half is already done on feature/sfa-curve-toLinear-densification.

B remains reachable via a three-line escape hatch for callers who want it (transform the CoordinateSequence directly and rebuild the CircularString). C survives as a CurvedGeometryFactory strict-mode flag — same diagnostic-mode role as FCP-DOVE Option C.

Smallest concrete next step

A one-line A / B / C ack on this issue, then an arch: commit on the spike branch pinning the choice in SPEC_AT_NS.md, then the implementation PR overrides apply(...) on each curve type with the similarity-detection + densify branch. The 8-test spec class shrinks to zero as the implementation lands per the §5 convention.

Phase-1 critical path now

F-CP   (Option A picked, awaiting ack -> implementation PR)
F-MC   (closed by F-MC-F-MS-spike, awaiting merge upstream)
F-MS   (closed by F-MC-F-MS-spike, awaiting merge upstream)
F-RD   (TestBuilder UI, separate track)

AT-NS  (Option A leaning, awaiting ack)

Door is open on every option if a downstream TAG surfaces a constraint that changes the trade-off before the implementation PR lands.

---

Assisted-by: Claude (Opus-4.7)

[grootstebozewolf]

Continuing — R-EQ §7-risk-#2 spike + PRC-SN Phase-7 spike

Two more rounds, both following the FCP-DOVE / AT-NS shape (spec doc + red-test class + probe + lean):

TAG	Branch	Position
R-EQ (§7 risk #2 — equalsExact semantics)	feature/sfa-curve-R-EQ-spike	Option A implemented and measured; zero regressions
PRC-SN (Phase 7 — snap-to-grid)	feature/sfa-curve-PRC-SN-spike	spec + probe; reveals today's reducer is more aggressive than Option C

R-EQ — measured at minimal cost

Root cause: LineString.isEquivalentClass is lenient (other instanceof LineString) so a CircularString calling equalsExact with a coordinate-identical LineString passes the equivalence gate and returns true. Polygon does not override isEquivalentClass, so CurvePolygon.equalsExact(Polygon) is already correctly false today — R-EQ is narrowly scoped to the two LineString-extending curve types.

Branching table

Option	Approach	Symmetry	Trade-off
A — override isEquivalentClass strict on curve side	curve overrides only	asymmetric (cs.eE(ls)==false, ls.eE(cs)==true)	Minimal, fixes the §7 violation, no jts-core change
B — tighten LineString.isEquivalentClass everywhere	breaks LinearRing↔LineString	symmetric	Much bigger jts-core change; future deprecation cycle
C — new parallel method	preserves all current behaviour	n/a	Adds API; doesn't fix equalsExact for existing callers

Lean: Option A. Implemented on the spike branch: two-method change (isEquivalentClass on CircularString and CompoundCurve).

Probe before/after the override

                              today (Option B baseline)   spike branch (Option A)
cs.equalsExact(ls)            true   <-- WRONG            false  <-- fixed
cc.equalsExact(ls)            true   <-- WRONG            false  <-- fixed
cc.equalsExact(cs)            true   <-- WRONG            false  <-- fixed
cs.equalsExact(cc)            true   <-- WRONG            false  <-- fixed
ls.equalsExact(cs)            true   <-- documented asym  true   <-- unchanged
cs.equalsExact(cs)            true                        true
lr.equalsExact(ls')           true   <-- intentional      true   <-- preserved
ls'.equalsExact(lr)           true   <-- intentional      true   <-- preserved
poly.equalsExact(ls)          false                       false

Posture: default mvn -pl modules/curved test is 55/55 green (zero regressions). On-demand spec is 6/6 green. The asymmetric ls.equalsExact(cs) == true is preserved by design — tightening LineString.isEquivalentClass would break the intentional LinearRing ↔ LineString equivalence, which is a much larger change. Documented in SPEC_R_EQ.md "asymmetry trap" + an explicit test (test_R_EQ_asymmetryIsDocumentedAndAccepted) that documents the contract.

Implementation PR is trivial: cherry-pick the two overrides, add a release-note bullet, add Javadoc on each curve type calling out the asymmetric contract.

PRC-SN — Phase 7 independent track with a surprising discovery

Spike followed the SPEC + probe + red-tests shape. The branching table is in SPEC_PRC_SN.md:

Option	Approach	Type stability
A — snap control points	preserved (type), arc drifts	The §7 "preserve on grid" branch
B — snap (R, centre, sweep)	preserved (type and arc)	Hard; not every snapped arc has control points on grid
C — densify then snap	LineString	The §7 "otherwise densify" branch
D — A when grid-friendly, else C	adaptive	The §7 phrasing made code

Lean: Option D, with a defined "grid-friendly" criterion: the snapped circle through the three snapped control points must have both centre and radius on the grid.

The discovery — today is worse than Option A or C

GeometryPrecisionReducer.reduce unconditionally strips CircularString to LineString via GeometryEditor.GeometryEditorOperation — even when there's nothing to snap:

input description                       out-type        out-pts  arc drift
integer-aligned half-circle             LineString      3        none
sub-cell drift snapping to integers     LineString      3        centre (4.89, 0.61) → (5.00, 0.00); R 4.81 → 5.00
sub-grid arc (off-grid centre)          LineString      3        centre (0.85, -0.31) → (0.50, 0.50); R 0.82 → 0.71
near-degenerate small arc               LineString      0        all coords collapse to origin
quarter-circle on grid                  LineString      3        none

Even the grid-aligned half-circle (CIRCULARSTRING (0 0, 5 5, 10 0)) loses its arc identity because the reducer's GeometryEditor rebuilds via the GeometryFactory.createLineString, which has no CircularString awareness.

So the choice isn't "A vs D" — the current behaviour is more aggressive than C (always degrade type, even when there's nothing to snap). PRC-SN is the right place to introduce any curve-type preservation through the precision reducer. Once the infrastructure exists, layering the grid-friendly check on top is straightforward.

Spec posture: 6 tests, 4 red / 2 green. The two greens pass for the wrong reason (today degrades unconditionally, which happens to match Option D's fallback assertion). The reds capture the gap. Probe runs on demand.

Implementation PR sketch: a new org.locationtech.jts.precision.curved.CurvedPrecisionReducer with isGridFriendly(CircularString, PrecisionModel) and a reduce(Geometry, PrecisionModel) entry point that dispatches curve subclasses through the Option-D branch and delegates to the standard reducer for everything else.

§7 risk register status after this round

Risk	TAG	Status
#1 — F-CP backward compat	FCP-DOVE	Option A recommended (earlier)
#2 — equalsExact semantics	R-EQ	Option A implemented + measured (this round)
#3 — non-similarity affine	AT-NS	Option A leaning (previous round)
#4 — arc-arc/arc-line indexing performance	N-AA / N-AL	not yet — needs benchmark spike (post Phase-5 design)
#5 — Z/M propagation across densified arcs	spans BUF / DSF / AT-NS / PRC-SN	tracked as a deferred policy item per spec docs

Plus PRC-SN (Phase 7) now has a spike and a discovery that informs Phases 2/3/4 too: any operation that goes through GeometryEditor will degrade curve types the same way the reducer does today. Worth flagging when those TAGs come up.

Door's still open on every option.

---

Assisted-by: Claude (Opus-4.7)