phase1: F-CP - pin structural CurvePolygon contract with a spec test

[grootstebozewolf]

Summary

Phase 1 / F-CP of the SFA Curve Awareness epic (locationtech/jts#1195) — Structural CurvePolygon. The gating sub-issue for every Phase-2 TAG that needs to talk about a curved boundary, area, or validity.

Stacks on top of #8 (rename + analyzer) which stacks on #7 (CI wake-up). Merge order: #7 → #8 → this.

The headline

F-CP needs no implementation work in C#. All ten sub-TAG assertions pass against enhancement/curved HEAD out of the box. This PR is the regression net that pins that, plus the doc explaining why.

The architectural background

On the JTS side, F-CP is a real implementation problem because Polygon.getExteriorRing() is typed LinearRing. The epic's §7 risk #1 (FCP-DOVE) tracks the option-A/B/C dovetail choice for the legacy accessor — see SPEC_F_CP.md and the F-CP option spikes.

On the C# side, the dovetail does not exist. NetTopologySuite.Curve's CurvePolygon extends Surface<Curve> (FObermaier's generic abstract base on NTS PR #526), not Polygon:

public class CurvePolygon : Surface<Curve>, ILinearizable<Polygon>
{
    public override Curve ExteriorRing { get; }
    public override Curve GetInteriorRingN(int index) { ... }
}

The shell and holes are typed Curve — the polymorphic base of LinearRing / LineString / CircularString / CompoundCurve. This is, in effect, the endpoint Option-B-on-Polygon would have reached if the legacy LinearRing accessor had never existed. So it never has to be widened, and there is no blast-radius count to do.

Sub-TAG mapping

Sub-TAG	C# status	Pinned by
FCP-S	green by architecture	FCP_S_compound_shell_…, FCP_S_arc_shell_…
FCP-MEM	green (verified)	FCP_MEM_compound_shell_members_retain_subtypes
FCP-H	green by architecture	FCP_H_arc_hole_exposed_as_CircularString
FCP-CP	green by architecture	FCP_CP_copy_preserves_shell_subtype, …_arc_hole_subtype
FCP-TL	green by architecture	FCP_TL_linearisation_walks_shell_and_holes
FCP-WKT	green (verified)	FCP_WKT_roundtrip_preserves_compound_shell, …_arc_shell
FCP-DOVE	not applicable	FCP_DOVE_not_applicable_in_csharp — reflection-asserts ExteriorRing returns Curve, not LinearRing. If a future refactor reintroduces a LinearRing-typed accessor, this test goes red and the epic §7 risk #1 conversation has to happen for this repo too.

What this PR adds

• docs/SPEC_F_CP.md — the C# companion to JTS' SPEC_F_CP.md. Sub-TAG-by-sub-TAG mapping, architectural justification for skipping FCP-DOVE, cross-reference pointers into NetTopologySuite.Proofs for the Phase-2 TAGs that will lean on the proofs explicitly.
• test/.../CurveAwareness/CurvePolygonStructuralSpec.cs — ten test methods covering the six functional sub-TAGs + the meta-test for FCP-DOVE. NTS convention (assert-style regression net, not the JTS "delete on green") — the class stays in the codebase indefinitely as a regression net.

Empirical result

Passed FCP_S_compound_shell_exposed_as_CompoundCurve
Passed FCP_S_arc_shell_exposed_as_CircularString
Passed FCP_MEM_compound_shell_members_retain_subtypes
Passed FCP_H_arc_hole_exposed_as_CircularString
Passed FCP_CP_copy_preserves_shell_subtype
Passed FCP_CP_copy_preserves_arc_hole_subtype
Passed FCP_TL_linearisation_walks_shell_and_holes
Passed FCP_WKT_roundtrip_preserves_arc_shell
Passed FCP_WKT_roundtrip_preserves_compound_shell
Passed FCP_DOVE_not_applicable_in_csharp

Test Run Successful.  Total tests: 10

WKTReaderEx already preserves COMPOUNDCURVE member subtypes on parse; WKTWriterEx already emits the structural tags. Hat tip to FObermaier's original 2021 design.

What's NOT in this PR

• Any implementation change to CurvePolygon.cs or the WKT/WKB IO. This PR is documentation + assertions.
• F-MC / F-MS / F-RD (the other Phase-1 sub-TAGs). F-MC and F-MS are reportedly half-already-free on the JTS Phase-1 base per JTS #1195 comment 4436748851; a follow-up PR will run the same SPEC + test pattern for both.
• Phase 2+ TAGs (M-LEN-CS, M-AREA-CP, V-CP, B-CP, …). They depend on F-CP landing, and now it has.

Test plan

• Local dotnet build -c Release -p:EnableApiCompat=false is green (0 errors, 3 pre-existing CS1591 warnings unrelated to this PR)
• Local dotnet test --filter "FullyQualifiedName~CurvePolygonStructuralSpec" reports 10 passed, 0 failed
• The NTSC0001 Curved-naming analyzer from arch: rename Curved -> Curve + add NTSC0001 analyzer as a guard #8 reports nothing on the new files (no stray "curved" identifiers — the renamed _arc_hole / arc_shell conventions go through cleanly)
• CI on this PR shows the matrix green (depends on ci: wake up the build on current .NET tooling #7 + arch: rename Curved -> Curve + add NTSC0001 analyzer as a guard #8 landing first)

AI assistance disclosure

AI-drafted, human-reviewed and curated. AI-generated portions are dedicated to CC0-1.0; human curation falls under the NTS BSD-3-Clause grant.

SPDX-License-Identifier: BSD-3-Clause AND CC0-1.0
Assisted-by: Claude (Opus-4.7)

🤖 Generated with Claude Code