C ABI surface + AOT-friendly double-precision core for ForceDirectedLayout

[matt-edmondson]

Summary

Note: this PR is stacked on top of #176 (the initial library extraction). The diff against main includes the #176 commits; review will be cleanest after #176 lands, at which point this PR's diff reduces to just the new work.

Follow-up to #176. Restructures ktsu.ForceDirectedLayout so a single source tree produces two artifacts:

1. A managed assembly consumed via NuGet (existing generic facade kept, now idiomatic .NET on top of a shared core)
2. A NativeAOT-compiled shared library (.dll / .dylib / .so) consumed via a C entry-point surface — Unreal plugins, C++ tooling, anything that can dlopen and call C functions

The C surface drove the design; the managed surface is the comfortable layer on top of the same core.

Layer cake

                ┌───────────────────────────────────────────────────┐
                │ NodeEditorEngine                                  │
                │   (System.Numerics.Vector2 float, for ImNodes)    │
                └──────────────────────┬────────────────────────────┘
                                       │ Vec2D↔Vector2 at boundary
                ┌──────────────────────▼────────────────────────────┐
                │ ForceDirectedLayout<TBody, TEdge>                 │
                │   generic facade, BodyAccessor / EdgeAccessor     │
                └──────────────────────┬────────────────────────────┘
                                       │ snapshot+commit
                ┌──────────────────────▼────────────────────────────┐  ┌───────────────────────┐
                │ ForceLayout                                       │◄─┤ NativeExports         │
                │   non-generic managed surface                     │  │   [UnmanagedCallers]  │
                │   ReadOnlySpan<NodePosition>, NodeInit/EdgeInit   │  │   try/catch→errcode   │
                └──────────────────────┬────────────────────────────┘  └───────────────────────┘
                                       │
                ┌──────────────────────▼────────────────────────────┐
                │ LayoutCore                                        │
                │   bare algorithm, BodyState[] / EdgeRef[]         │
                │   no allocations per step, no reflection          │
                │   double precision                                │
                └───────────────────────────────────────────────────┘

C API (V1 surface lock)

LayoutHandle Layout_Create(const LayoutSettings* config);
int32_t      Layout_Destroy(LayoutHandle handle);
int32_t      Layout_SetSettings(LayoutHandle, const LayoutSettings*);
int32_t      Layout_SetNodes(LayoutHandle, const NodeInit*, int32_t count);
int32_t      Layout_SetEdges(LayoutHandle, const EdgeInit*, int32_t count);
int32_t      Layout_SetPinned(LayoutHandle, int32_t nodeIndex, uint8_t pinned);
int32_t      Layout_Step(LayoutHandle, double dt);
int32_t      Layout_Solve(LayoutHandle, int32_t maxIterations, double tolerance);
int32_t      Layout_GetPositions(LayoutHandle, NodePosition* outBuf, int32_t bufLen);
int32_t      Layout_GetIndexOf(LayoutHandle, int32_t nodeId, int32_t* outIndex);
int32_t      Layout_GetNodeCount(LayoutHandle, int32_t* outCount);
int32_t      Layout_GetLastErrorMessage(uint8_t* outBuf, int32_t bufLen);

• Opaque-handle style. Handles are GCHandle.Alloc(ForceLayout). Pair every Create with a Destroy.
• All structs [StructLayout(Sequential)], fixed-size primitives only.
• Every export wraps a try/catch that converts managed exceptions to error codes. No exception escapes into native code.
• Reference header committed at ForceDirectedLayout.Native/ktsu_force_directed_layout.h alongside the AOT-emitted one.

What changed in the core

• Vec2D: new double-precision blittable 2D vector. Replaces System.Numerics.Vector2 (which is float) throughout the layout core.
• PhysicsSettings: managed record, plain doubles. The ktsu.Semantics.Quantities typed wrappers (Force<float> etc.) are gone — they generated AOT/trim concerns and the typed affordance wasn't worth the friction at the boundary.
• LayoutSettings: POD mirror of PhysicsSettings, crosses the C boundary unchanged.
• LayoutCore: the algorithm in its bare form. Operates on flat BodyState[] and EdgeRef[] buffers, no allocations per step, no reflection, no generics, no managed-only types.
• ForceLayout: non-generic managed surface. Accepts NodeInit / EdgeInit POD bulk submission, returns ReadOnlySpan<NodePosition> for zero-copy reads.
• ForceDirectedLayout<TBody, TEdge>: refactored to delegate to LayoutCore via snapshot+commit. Accessor signatures now use Vec2D.
• NodeEditorEngine: bridges float Vector2 ↔ Vec2D at the accessor boundary. Its public surface stays float-based.

Build

• ForceDirectedLayout.csproj: IsAotCompatible=true, IsTrimmable=true, EnableTrimAnalyzer=true, EnableAotAnalyzer=true, EnableSingleFileAnalyzer=true. Trim/AOT warnings fail the build so reflection drift is caught immediately.
• ForceDirectedLayout.Native.csproj: thin AOT publish project. <PublishAot>true</PublishAot>, <NativeLib>Shared</NativeLib>, <TrimMode>full</TrimMode>, <InvariantGlobalization>true</InvariantGlobalization>. Per-platform binaries via dotnet publish -r <rid>.

Reserved Vec2D Anisotropy on EdgeInit for V2 (execution vs data-pin biasing in node-editor consumers) — adding it later would be an ABI break.

Reserved / explicitly not in V1

• Per-edge anisotropy is plumbed through EdgeInit and EdgeRef.Anisotropy but the algorithm ignores it.
• No callback exports yet. When they land they'll use delegate* unmanaged<...>, not Func<>/Action<>.
• No native test harness (C/C++ link target). Worth adding to CI once a per-platform publish matrix exists.

Test plan

• dotnet test --project tests/ForceDirectedLayout.Tests passes on the project's CI (covers repulsion, pinning, solve convergence, settings round-trip)
• dotnet build ForceDirectedLayout.Native succeeds
• dotnet publish ForceDirectedLayout.Native -c Release -r linux-x64 produces a .so (and the equivalent for win-x64 / osx-arm64 in CI)
• Confirm the AOT-generated .h matches the hand-authored reference header in field order and primitive sizes
• Confirm CleanImNodesDemo still settles into a left-to-right layout with all PhysicsSettings sliders and presets
• Confirm pinning/dragging behaviour in the demo
• Catch any trim/AOT analyzer warnings introduced by future changes — they fail the build by design

---

Generated by Claude Code

[sonarqubecloud]

Quality Gate failed

Failed conditions
1 Security Hotspot
0.0% Coverage on New Code (required ≥ 80%)
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE