[HengyuLi-Ozaki-lab]

What

The ctypes loaders of eqlib, trlib and fplib (python/<mod>/_ffi.py) learn the two things Windows needs:

• Library name. On Windows the default search looks for libeqapi.dll, libtrapi.dll and libfpapi.dll in
  <repo>/<mod>/ and <repo>/lib/. Every other platform keeps .so, macOS included (that is the name
  make lib<mod>api.so produces there). The "not found" errors name the file that was looked for.
• Dependent DLLs. Since Python 3.8 the DLLs a library depends on are no longer found through PATH. On Windows
  load_library now makes the path absolute and registers its directory with os.add_dll_directory, once per
  directory (the handles are kept in a dict keyed by the normalised path, because the MCP servers open a fresh library
  handle after every finalize). The gfortran runtime DLLs (libgfortran, libquadmath, libgcc_s, libwinpthread)
  are expected next to the library. For a full path ctypes already searches the library's own directory, so the
  registration is a second line of defence, as the comment in the code says; the same comment explains why
  winmode=0 must not be used to "fix" a load error: it skips registered directories.

The three modules get the same change and differ only in the module name. Each package gets a
tests/test_platform_libname.py (8 tests per package, 24 in all) that fakes Windows (sys.platform,
os.add_dll_directory, ctypes.CDLL) so it runs on Linux and macOS.

Why

Downstream, the TASK Web Client's Windows installer ships lib<mod>api.dll beside the gfortran runtime DLLs. On
develop such a build loads only when EQLIB_PATH / TRLIB_PATH / FPLIB_PATH name it; the default search knows
only .so names.

In use downstream (TASK Web Client) since 2026-09-25.

Checked

• python/eqlib python/trlib python/fplib, with upstream CI's flags (--forked --timeout=120 --timeout-method=signal): 172 passed, 8 skipped, 1 xpassed. macOS (Apple silicon), gfortran 15.2.0 (MacPorts,
  -O0 -fbounds-check -fcheck=all), Python 3.12.13, pytest 9.0.3, mcp 1.27.1, bpsd develop fb8414f.
• The 8 skips are the equivalence tests of eqlib (2), trlib (3) and fplib (3), Linux-only since fplib + wrxlib equivalence tests fail 1e-10 tolerance on develop (mismatches ~1e-9) #213
  ("Equivalence tests are Linux-canonical"). They were not run here and are left to upstream's Linux CI; this change
  does not alter what they load on Linux. The xpass is the existing test_NSMAX_in_range (tr_tst2 fixture: NSMAX>2 mutation produces NaN scalars (RNU/RTU species 3+ unpopulated) #189).
• The Windows branch of load_library was not run on Windows here; the new tests simulate it. Against
  develop's _ffi.py six of the eight tests per package fail; the other two (macOS and Linux keep .so; nothing is
  registered off Windows) are regression guards.

Things to know

• Off Windows nothing changes. With sys.platform set to linux, darwin, cygwin and freebsd, the candidate paths,
  the default path and the "not found" message of each of the three wrappers are byte-identical to develop's (12
  cases compared).
• On Windows this is not a regression. Upstream documents an Ubuntu install (INSTALL_Ubuntu.md) and its
  Makefiles build only lib<mod>api.so (there is no .dll target); a library named through EQLIB_PATH and its
  siblings loads as before, since those variables are read before the candidate names.
• Size. The 519 added lines are 399 of tests (133 per package) and 120 of loader (40 per wrapper).
• One wart. On Windows the "not found" message now reads libeqapi.dll not found at ... Tried EQLIB_PATH and [...]. Build it via make -C eq libeqapi.so or set EQLIB_PATH. The hint names the .so target because that is the
  only one the Makefiles have. Either of two small changes would remove the oddity, and the maintainers can pick: add
  .so as a second candidate on Windows (after .dll), or reword the hint on Windows. Say which and it will be done.
• tilib, wrlib, wrxlib and totlib are not changed (still .so only), and neither is the MONO_LIB_PATH probe
  in python/_runtime_mode.py; it loads by the path it is given, which works for an absolute path. This pull request
  is limited to the three wrappers a Windows installer needs first.

Scope

Based on current develop (4a5d977) and standing alone on it: the results above were obtained on develop plus
these three commits. Independent of #226 and of #231, #232 and #233. The change shares python/eqlib/_ffi.py with #226
and python/fplib/_ffi.py with #233, in different hunks; trial merges with #226's head (682d9af), #231, #232 and #233
are conflict-free.

🤖 Generated with Claude Code

[k-yoshimi]

Reviewed at 63b1f425 (based on current develop tip). Approving.

Verified locally (macOS arm64, stock .sos linked into a worktree of the PR head, pytest 9.1.1 --forked --timeout=120 --timeout-method=signal, strict-subTest override from #243 active): python/eqlib python/trlib python/fplib → 172 passed, 8 skipped (Linux-canonical equivalence), 1 xfailed (#189), matching the PR body. The three loader diffs and the three test files are identical after name normalisation (only the <repo>/<mod>/ docstring path differs), so there is one implementation to reason about.

Decision on the "one wart": please take the second option, reword the hint on Windows (e.g. "Build lib<mod>api.dll from the Fortran sources or set <MOD>LIB_PATH"). Adding .so as a second candidate on Windows would advertise a file ctypes cannot load there. Happy to merge once that is pushed (CI will re-run on the fork push; ping me and I will approve the workflow run).

For the record: ctypes.CDLL(..., mode=...) ignores mode on Windows, so passing the RTLD_LAZY fallback through is harmless. #226 also edits python/eqlib/_ffi.py (prototype additions in a different hunk); this PR goes in first, so #226 will need a small rebase.

[k-yoshimi]

Independent Codex review (second reviewer, read-only) found no HIGH items. Two things to fold into the same push as the hint reword, then this merges:

1. MED — MONO_LIB_PATH with a bare relative value bypasses the new normalisation on Windows. python/_runtime_mode.py:40-51 probes with ctypes.CDLL(str(p)) before any _ffi.load_library runs; Path.exists() succeeds from cwd, but a bare libtotapi_mono.dll goes through Windows' secure search (no cwd, no add_dll_directory) and fails to find the DLL or its gfortran neighbours. Either make p absolute there on Windows (p = p.resolve() before the probe, and return the absolute path), or state in the PR/README that mono mode is not supported on Windows yet. The PR body already says the probe "works for an absolute path", so the one-liner is the natural choice.
2. LOW — a failed load leaves its directory registered. The os.add_dll_directory handle is cached before ctypes.CDLL succeeds (python/eqlib/_ffi.py:302-310 and the tr/fp twins). If the file exists but is wrong-arch or has missing dependencies, the directory stays in the process-wide search set and the dict grows per distinct failing path. Register, try the load, and on failure handle.close() without caching.
3. The docstrings of _default_lib_path() / load_library() and the module header still describe .so only; one clause each (".dll on Windows") keeps them honest alongside the hint reword.

Confirmed by Codex (matches my review): ctypes.CDLL ignores mode on Windows and, for a path containing a separator, adds LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR; cygwin stays on the .so path by design; repeated MCP reopen cycles are unaffected; the tests exercise the real _candidate_paths / load_library (not a copy), though they cannot see native Windows semantics — a Windows smoke run downstream remains the real validation.

[HengyuLi-Ozaki-lab]

Pushed 75f1fb17, the same change in the three loaders:

1. The hint on Windows reads "Build lib<mod>api.dll from the Fortran sources or set <MOD>LIB_PATH." Off Windows the message is unchanged byte for byte, and a test holds it.
2. MONO_LIB_PATH (python/_runtime_mode.py): on Windows the path is made absolute before the probe, and that path is returned. I used os.path.abspath, as the loaders do, rather than Path.resolve(): it does not follow links or substituted drives. Off Windows the value is used as given.
3. A failed load leaves nothing registered. The directory handle is cached only after ctypes.CDLL and the prototypes succeeded; on a failure it is closed. A directory registered by an earlier successful load is not touched.
4. Docstrings: the module header, _default_lib_path() and load_library() say .dll on Windows.

Tests: five more per package and three for the mono path (Windows simulated, as in the rest of the branch); ten of the eighteen fail against 63b1f425. python/ on this branch: 765 passed, 35 skipped, 1 xpassed with CI's flags; with the mono image, the four test_mono_* files: 17 passed. develop has moved to a0b58408 (#242, #243) since your review: this branch merges into it without a conflict, and on develop with #231, #232, #233 and #240 merged together python/ gives 831 passed, 35 skipped, 1 xfailed (#243's strict subTest active).

Not changed, for you to say whether it belongs here: the MCP servers wrap the loader's FileNotFoundError and append their own "Build it via make -C <mod> lib<mod>api.so" (eq_mcp, tr_mcp, fp_mcp: _wrap_*_error), so on Windows an MCP client still reads the reworded hint followed by the old one.

The description above predates this push in three figures ("519 added lines", "8 tests per package", and "neither is the MONO_LIB_PATH probe [changed]"). Still true: none of this has run on Windows here. The workflow run needs your approval.

[HengyuLi-Ozaki-lab]

develop (963ae3dc) is merged in, 0ec0f008, and one fix follows, e92c2183.

• The merge. The conflict was the end of load_library in the eq, fp and tr wrappers. feat(abi): every library reports its state-struct layout; wrappers refuse a mismatch (#246) #261's layout check now sits inside the block that closes the newly registered DLL directory, so a library refused for its layout leaves no directory in the search set either; the order is develop's (the check, then the prototypes). The cases of test_platform_libname.py fake the loaded library, which the check refuses (24 of 39 failed), so they now patch it out (it has its own tests), and one case per module checks the refusal path: the error, the handle closed, nothing registered.
• e92c2183: with .dll names, the layout check's rebuild hint said make -C eq libeqapi.dll (and make -C tot libtotapi_mono.dll), targets no Makefile has: what this pull request fixed in the not-found hint, back on the new path. For a .dll name the hint is now "Rebuild it: libeqapi.dll from the Fortran sources" (and the same in the mismatch message); one case in python/tests/test_abi_check.py.

macOS, clean build: 1009 passed, 38 skipped with the CI flags. Nothing was run on Windows.

[k-yoshimi]

Delta review of 0ec0f008 (merge of develop 963ae3dc) + e92c2183, in-house + independent Codex. No HIGH, no MED that this PR introduces. Approving the delta; two LOWs to fold into the same push, then this merges.

Verified

• The hand resolution in the three _ffi.py is the right one: check_state_layout call and AbiMismatchError → <Mod>libAbiError re-raise byte-identical to develop, now inside the try/except BaseException so a refused layout closes the just-registered DLL directory cookie and writes no dict entry. POSIX path behaviourally identical to develop (new_dir_handle is None). The three modules differ only in the module token.
• test_platform_libname.py: the autouse no-op of check_state_layout makes nothing vacuous (every case still asserts on its own events). The new refusal-path case is real: moving the layout check back outside the cleanup block makes exactly that case fail.
• e92c2183: the .dll branch precedes the mono branch, so libtotapi_mono.dll gets it too; the test covers both names × both refusal branches.
• Local: 98 passed (abi_check + 3× platform_libname + eqlib/fplib/trlib suites) with the CI flags, macOS, stock .sos.

LOW, please fold in

1. python/_abi_check.py:67 lib_name.endswith(".dll") is case-sensitive; an explicit EQLIB_PATH ending in .DLL (valid on Windows, basename keeps the case) falls through to the make -C eq LIBEQAPI.DLL hint this commit removes. .lower().endswith(".dll").
2. python/_abi_check.py:81-82 the no-query message reads "Rebuild it: libeqapi.dll from the Fortran sources." — a fragment; the wrappers' not-found hint says "Build libeqapi.dll from the Fortran sources". Align the wording.

Not this PR (Codex MED, pre-existing from #261): on a layout refusal the directory cookie is closed but the CDLL handle is never FreeLibrary'd / dlclose'd, so on Windows a refused DLL stays mapped and file-locked until the process exits, which blocks the rebuild the hint asks for. Filed as a follow-up issue; not blocking here.

[HengyuLi-Ozaki-lab]

Both LOW points are in c268696d: _abi_check.py tests .lower().endswith(".dll"), so an explicit EQLIB_PATH ending in .DLL gets the Windows hint too, and the hint is a sentence: "Build libeqapi.dll from the Fortran sources." for a library without the query symbols, "... build libeqapi.dll again from the Fortran sources or update python/eqlib/_ffi.py." for a mismatch. The messages for a .so name are unchanged (compared with develop's for a module library and the mono image). The test covers libxxapi.dll, libtotapi_mono.dll and LIBXXAPI.DLL, without subTest; with the case-sensitive test it fails under --forked. #266 is not touched here.

macOS: the whole suite 1009 passed, 38 skipped with the CI flags. This head merges cleanly with develop 4b5463e4.

[k-yoshimi]

Delta review of c268696d (the two LOW items), run through the full review cycle (Codex + in-house domain/test-oracle lenses + docs/workflow review), with the suite run locally under the CI flags.

Verdict: approve. Both LOW points are closed as described: .lower().endswith(".dll") catches LIBXXAPI.DLL, the hints are sentences, the non-.dll wording is byte-identical to before on both error paths (every loader passes os.path.basename), and the rewritten test fails on the previous case-sensitive code (the reviewers ran it against a reconstruction of the old helper).

Local: 1008 passed, 38 skipped, 1 failed (the known Python 3.10 ExceptionGroup case, same on develop). CI green at c268696d.

Two small things the reviewers raised; neither blocks the merge:

• python/tests/test_abi_check.py:113-123 — without subTest, CI (which installs pytest-subtests) stops at the first failing case and hides the other five; attribution is preserved because the expected text embeds the name, so this is a convenience only.
• CHANGELOG.md has no entry for the Windows .dll support. Every PR merged recently carries one; a short Added line (the .dll lookup, os.add_dll_directory registration with rollback on a failed load, the MONO_LIB_PATH normalisation) would be welcome, in this PR or a follow-up.

Noted, not requested: tilib/wrlib/wrxlib/totlib keep .so-only loaders, as the PR text says; a follow-up when there is a Windows user for them.

Merge waits for the maintainers' instruction, as agreed.