feat(dotnet): make the .NET binding work on macOS and Linux via the pure-C shimtion

[zzcgumn]

What and why

DDS_Core is a complete, idiomatic .NET wrapper — 46 P/Invokes, a full blittable
DataModel, SafeHandle lifetimes. But it only ever worked on Windows, because the
native library it loaded (dds_native.dll) is built solely by
solution/dds_native.vcxproj under MSVC.

//jni:dds_shared already builds a self-contained shared library on all three
platforms. This PR closes the ABI gap between the two so the existing managed API
runs unchanged on macOS, Linux, and Windows.

The gap

The binding's fourteen modern entry points bound dds_* from dds_api.hpp. Those
symbols are not exported on Linux or macOS — the export lists pin the ABI to
dll.h + dds_c_api.h:

$ nm -gU bazel-bin/jni/libdds.dylib | grep dds_
_dds_c_calc_dd_table  _dds_c_calc_par  _dds_c_create_solvercontext_default
_dds_c_destroy_solvercontext  _dds_c_solve_board

So all fourteen would have thrown EntryPointNotFoundException off Windows. The
other 30 P/Invokes are the legacy flat API and already resolved.

Two causes: five functions existed only under dds_c_* names, and nine had no shim
equivalent at all. This was invisible because Windows has no .lds branch — its DLL
exports the broader DLLEXPORT set, including dds_api.hpp.

What changed

Native (library/src/api/dds_c_api.{h,cpp}) — nine functions added to the shim:
config-based context creation, calc_dd_table_pbn, TT configure/resize/clear, both
resets, and the two logging passthroughs. Each follows the file's existing pattern —
null guards plus a catch-all so no C++ exception unwinds through the C ABI.
SolverConfig is decomposed into scalars rather than mirrored as a C struct, keeping
the shim pointer-only and POD-only; TTKind crosses as an int.

Export lists regenerate from the headers, so //jni/tests:export_set_test validated
the result with no wiring change.

Managed (dotnet/DDS_Core) — the fourteen P/Invokes retarget onto dds_c_* via
EntryPoint, so no call site in DDS.cs or SolverContext.cs moves. The library
name becomes dds (letting .NET's probing supply the lib prefix and per-OS
extension). dds_log_append marshals UTF-8 explicitly instead of relying on the
platform-dependent CharSet.Ansi default. A resolver honours DDS_LIBRARY_PATH —
the counterpart of the JVM binding's -Ddds.library.path — falling back to default
probing when unset, and failing loudly with the attempted path when set but wrong.

Also removes two commented-out calc_par declarations: they are plain C++ with no
extern "C" or DLLEXPORT, so they were never bindable on any platform.

Two pre-existing memory bugs found and fixed

Adding coverage for the shim surfaced two faults in transposition-table lifecycle.
Both predate this PR, both are reachable from the existing public API, and neither
involves the new shim entry points — each was reproduced through the
reference-taking C++ API with no dds_c_* call in the trace.

1. Use-after-free in clear_tt() — affects the default configuration

allocated: TransTable{L,S}::make_tt
freed:     TransTable{L,S}::return_all_memory   ← clear_tt()
read:      TransTable{L,S}::lookup              ← next solve

clear_tt() returned the TT's memory but kept the instance.
SearchContext::trans_table() only checks whether tt_ is non-null, so it handed
that husk straight back and the next lookup read freed pools.

This hits the default Large TT — no TT-kind switch required. The sequence is just
clear_tt() followed by a solve, which the .NET binding exposes directly as
SolverContext.ClearTT() then SolveBoard(). Caught by ASan on Linux CI.

The fix disposes the instance, making the already-documented "recreates lazily on
demand" behaviour real: tt_ becomes null and the next trans_table() rebuilds from
the owner's config. Nothing is lost — kind and memory limits live in
SolverContext::cfg_, not the instance, and the destructor returns the memory either
way. Disposal also keeps the fix off the hot path, since ab_search calls
trans_table() per lookup.

2. Null dereference in TransTableS::reset_memory() — Small TT only

solve → configure_tt(Small) → clear_tt() → reset_for_solve()
    → null deref in TransTableS::init_tt()

reset_memory() ignored tt_in_use_ and re-initialised over freed pools. Fixed with
the guard TransTableL::reset_memory() already had (pool_ == nullptr), which is why
only the Small TT was affected.

Reviewer note: fix (1) largely subsumes this one — with the instance disposed,
maybe_trans_table() returns null and reset_for_solve() no longer reaches a
memory-less table. The guard is retained as defence in depth and for symmetry with
TransTableL, but it is no longer load-bearing. Reasonable to ask for it to be
dropped as unreachable.

Testing

• //library/tests:dds_c_api_test (new, 13 tests) — null-handle and null-argument
  rejection, both TT kinds, reconfiguration, resets, logging, PBN/binary agreement,
  plus regressions for both bugs above.
• dotnet/DDS_Core.Tests (new, 19 tests) — layout, smoke, and lifecycle. Between
  them every one of the fourteen retargeted P/Invokes is exercised, so a missing
  EntryPoint fails here rather than in a consumer.
• CI — managed build and test added to Linux, Windows, and macOS. Windows matters
  most: it is the platform this change could regress, and the Bazel-built dds.dll
  path is covered by nothing else (the JNI tests are target_compatible_with-excluded
  there). macOS is included because it is the only CI coverage of AArch64.

The layout tests carry the most weight. The managed structs had only ever been
exercised against the MSVC ABI, and a mismatch on SysV or AArch64 corrupts results
silently rather than throwing. Expected sizes and offsets are derived from the C
headers via offsetof/sizeof, not from running the C# — asserting what the code
already does would prove nothing. They pass, which is the first confirmation the
layouts are correct off Windows.

Verified locally on macOS/arm64: ASan and TSan clean across //library/tests/...,
59/59 Bazel tests, 19/19 .NET tests.

Notes for reviewers

• A claim in the commit history is corrected. <Platforms>x64</Platforms> was
  not blocking Apple Silicon, as I initially assumed. It only declares the IDE's
  valid platform list; it never set <PlatformTarget>, so the assembly was already
  AnyCPU and arm64 builds already worked. That change is declarative, not unblocking.
• The test project targets net8.0 with <RollForward>Major</RollForward> so it
  also runs where only a newer major runtime is installed. CI pins an 8.0 SDK, where
  the property is inert.
• The resolver registers from a static constructor, not [ModuleInitializer]: the
  runtime guarantees a type initializer runs before that type's first P/Invoke, which
  is the same guarantee without CA2255's objection to module initializers in libraries.
• CI resolves the native library via bazel info bazel-bin rather than the
  bazel-bin symlink, which is configuration-dependent and moves between --configs.
• Local ASan on macOS needs DEVELOPER_DIR exported
  (/Applications/Xcode.app/Contents/Developer), otherwise Bazel's Xcode locator
  fails against Xcode 26.5 and every sanitizer target fails to build. Bug (1) reached
  CI because of this. Worth adding to the dev setup notes.

Deliberately out of scope

• NuGet packaging. RID-specific assets (runtimes/<rid>/native/…) and a
  multi-platform package are a follow-up, mirroring how the jar followed the JVM
  shared library.
• Retiring solution/dds_native.vcxproj. Still present for interactive VS
  debugging; DDS_Core.slnx still build-depends on it, and it now emits a library
  name nothing loads. (That solution also does not build under dotnet build because
  it includes a C++ project needing VS MSBuild — pre-existing, confirmed against the
  base.)
• Moving dds_shared out of //jni. It now serves three ecosystems, but renaming
  is best done with the packaging work rather than mid-ABI-change.

Specs

specs/dds-public-api.md had three claims this work falsifies (the shim as "a thin
subset… no *PBN twins and no TT configure"; .NET binding dds_*; the PBN pairing not
extending to the shim) — all corrected. Adds specs/dotnet-binding.md, which the repo
lacked despite having one for the Python and JVM bindings.

Closes #227

[zzcgumn]

@timanderson, your feedback on this would be much appreciated.

[zzcgumn]

@mortensp, I don't think this breaks the visual studio build. Any chance you can check?

[timanderson]

Thanks for doing this @zzcgumn , I checked out the PR and it works on macOS. I have no idea what a "pure-C shimtion" is though!

I am not sure that the changes the AI made to DdsNative.cs were necessary, despite the claim that "So all fourteen would have thrown EntryPointNotFoundException off Windows" this was not the case with the tests I did before on the Mac as you can see from the output that I pasted, unless there is something I am missing (quite possible).

Rather than manually copying the shared library file or setting DDS_LIBRARY_PATH I personally prefer to modify the .csproj to copy the shared library to the output, which you can do with conditions so the right library is copied for the OS on which you are running. Not a big deal.

As the AI notes, if you run dotnet build in the DDS_Core directory it will fail because it will look at the .slnx file which does a Windows-specific build. It is easy to get round this by typing:

dotnet build DDS_Core.csproj

but adds a bit of friction. But some on Windows may prefer to load the solution and not use Bazel which I understand. It would make sense to make the DLL name and the output location the same whether using Bazel or MSVC to build it.

As it stands I think the PR could end up being a little bit annoying for both the Windows and non-Windows users.

Incidentally, .NET 8 goes out of support in November despite being an LTS release (blame Microsoft).

[zzcgumn]

As it stands I think the PR could end up being a little bit annoying for both the Windows and non-Windows users.

I am only using the C++ and Python interfaces actively in my own work. What you say about build artefact locations makes sense, but I am not in a position to have a good judgement on how to improve. I am thinking that the best way forward is to merge this and hope that people who use .net actively can make contributions that reduce the friction. Does this make sense?

[timanderson]

I think the idea for Windows users is that they can open DDS_Core.slnx in Visual Studio, build, and everything works. The PR does break this. Actually it was already slightly broken for me; I was getting linker errors until I added deal_fanout.cpp and deal_fanout.hpp to the solution; I am not sure why they were missing. But after doing that it works. If I try that having checked out the PR I get a warning about "unknown project configuration mappings" and Visual Studio no longer builds the .NET projects; this is because of changes made to the project configuration. I think this should be fixed before the PR is merged.

[zzcgumn]

I don't have access to Visual Studio, only Visual Studio Code which as far as I can tell does not understand the DDS_Core.slnx build file. @timanderson or @mortensp , is anyone of you able to fix the visual studio solution files? I am happy for you to push to this branch or open a pull request into it.