[k-yoshimi]

Fixes #246 (develop-targeted, so close by hand after merge). Design: docs/superpowers/specs/2026-10-17-c-abi-state-layout-check-design.md (option 2 of the issue; the size-negotiated _v2 getter is deferred until an out-of-tree C consumer exists).

Why

Each module fills one fixed-layout struct through X_get_state(X_state_t*), and the only rule was "append, bump the macro where there is one, rebuild in the same commit". Nothing checked it at run time, so a library and a wrapper from different commits failed silently: a library with a longer struct wrote past the wrapper's allocation (56 bytes in #233's case, during the unconditional zeroing even on an error return), a library with a shorter one left the appended fields as plausible 0.0 all the way to the MCP clients. tr and tot had *_STATE_ABI_VERSION as a compile-time #define only; the other five had nothing, and test_size_matches_header_math compares ctypes arithmetic with numbers typed into the test.

What (same shape ×7: tr fp eq ti wr wrx tot)

• Fortran is the source of truth. X_state.f90: INTEGER(C_INT), PARAMETER :: X_STATE_ABI_VERSION next to the BIND(C) type (tr, tot = 2 as before; eq fp ti wr wrx = 1). X_api.f90: X_state_abi_version() returns it, X_state_size() returns C_SIZEOF of the type; both BIND(C), no lifecycle check, callable before X_init. The mono image exports all twelve automatically (libtotapi_mono_inspect gets a gate for them).
• Header mirrors it. X_api.h: the #define (new for five modules, with the History block tr/tot already had), the two prototypes, <stddef.h> for size_t.
• C drivers cross-check Fortran vs header. tests/c_abi/test_negative.c (first thing in main, before init) and test_run_so.c (through dlopen, exit 92 = symbols missing, 93 = mismatch) compare X_state_abi_version() with the macro and X_state_size() with sizeof(X_state_t). This is the BIND(C)-type-vs-C-struct check the issue asked for. CI gets a step running the six per-module X_api_check_so (tot's tot_api_check_all already ran); the static-link drivers stay local (tr's and fp's do not link on macOS, pre-existing g3d limit).
• Python refuses a mismatch at load. New shared python/_abi_check.py::check_state_layout, called from every _ffi.py::load_library right after ctypes.CDLL and before any prototype or struct; X_STATE_ABI_VERSION constant in each _ffi.py next to the X_MAX_* constants; new XlibAbiError(XlibError) in each errors.py (exported from the package) so except XlibError keeps working. Three refusals, each naming the fix: the library exports neither symbol (built before C-ABI state structs have no size/version negotiation: struct growth silently corrupts old callers or returns zeros to new callers #246), the version differs (a reorder keeps the size), the size differs.
• Tests. python/tests/test_abi_check.py (helper, no .so, 7 cases: match attaches prototypes, no symbols, one symbol, larger, smaller, version drift, error class). Per wrapper in tests/test_ffi.py::TestLibraryLayout (4 cases: real library matches; a ctypes struct one field short is refused with both sizes; version drift through load_library raises the wrapper's own XlibAbiError; a stand-in without the query is refused). Guards in setUp.
• Docs. "State struct layout rule" section in all seven docs/X-library/architecture.md; "Library layout check" in all seven python/Xlib/README.md; extending-tr.md (en, ja) step 5 now says bump the PARAMETER and the macro together; CHANGELOG.

Scope boundary: X_state.f90 / X_api.f90 / X_api.h are the L-2 C-ABI layer; no module physics, so outside the lead-sign-off rule.

Sequencing

#233 (fp global scalars, external, open) grows fp_state_t: after this merges it bumps FP_STATE_ABI_VERSION 1 → 2 in fp_state.f90, fp_api.h and python/fplib/_ffi.py (one comment on #233 says so). #244 follows #233.

Verification (macOS gfortran)

• All seven .so and libtotapi_mono.so rebuilt; every wrapper loads its library and reports the same version and size as its ctypes struct (tr v2/72128, fp v1/38432, eq v1/80816, ti v1/105640, wr v1/20448, wrx v1/70424, tot v2/72144), also through the mono image.
• make -C X X_api_check_so → OK for all seven; libtotapi_mono_inspect gate 1b → 12 symbols; cc -std=c99 -Wall -Wextra -fsyntax-only clean on all 14 drivers; X_api_check_all static links hit the pre-existing macOS g3d limit for tr/fp (CI runs tot's and the six dlopen drivers).
• pytest python/ test_run/scripts/tests --forked --timeout=120 --timeout-method=signal → see the first comment.
• Reviews: in-house + Codex (first comment).

🤖 Generated with Claude Code

https://claude.ai/code/session_01TA2KahTs3qLMZL6yjSsWwT

[k-yoshimi]

Pre-push reviews (in-house + Codex, read-only, on the full 84-file diff; the final f86cfab folds their findings in).

Verified by the reviewers: in all seven X_api.f90 the new USE X_state, ONLY: X_STATE_ABI_VERSION is a standalone statement before the continued USE, the extra PUBLIC sits before CONTAINS, and no pre-existing symbol clashes; C_SIZEOF of the BIND(C) local returns INTEGER(C_SIZE_T) (the probes are 20 to 106 KB, above gfortran's 64 KiB stack-var default, so they go to static storage, never written); <stddef.h> is inside the guard and before extern "C", the new macro block sits between the last X_MAX_* and enum X_error; the test_run_so.c dlsym block is after the return 91 check and before the cycle in all seven, %lu casts are right; _ffi → .errors has no cycle, _abi_check is importable wherever any wrapper is, the check runs before _apply_prototypes; the stale-struct test shrinks every struct (so it cannot false-pass); the mock.patch.object test reads the module global at call time; no existing test mocks ctypes.CDLL through load_library; the mono gate's nm regex matches Linux (T eq_state_size) and macOS (_eq_state_size) and correctly omits wr (not in the mono image).

Findings, all applied:

• HIGH (Codex, on the spec's wording): a query-only design cannot protect a caller that predates it (a pre-C-ABI state structs have no size/version negotiation: struct growth silently corrupts old callers or returns zeros to new callers #246 wrapper or C program never asks, and X_get_state still takes no buffer size). True, and the spec's "both failure modes" sentence overstated it; the spec, CHANGELOG and READMEs now say the check protects callers from this change on, that the only such callers are this repository's (rebuilt with the library), and that an out-of-tree C consumer is the case for the deferred _v2 getter.
• MED (Codex): a wrapper routed to the mono image said make -C eq libtotapi_mono.so; the hint now says make -C tot libtotapi_mono.so (two helper tests).
• MED (in-house): TotAbiError typo in the tot architecture doc → TotlibAbiError.
• LOW: duplicate WrlibAbiError definition (left by an aborted scripted edit); __all__ in eq/ti/tot errors.py; the helper docstring said _apply_prototypes calls it (it is load_library); spec status / "fourteen symbols" / "~5 MB" corrected; test_run_so.c header comments list the new exit codes 92/93; extending-tr.md line references replaced by names; tr/tot X_api.h rule paragraphs now mention the PARAMETER and the runtime check; architecture tables say "5 (6) functions + 2 layout queries".

Local: pytest python/ test_run/scripts/tests --forked --timeout=120 --timeout-method=signal → 954 passed, 35 skipped, 1 failed (test_close_raises_exception_group_when_multiple_modules_fail, the known macOS / py3.10 case). X_api_check_so OK for all seven; libtotapi_mono_inspect gate 1b OK; the 14 drivers pass cc -std=c99 -Wall -Wextra -fsyntax-only. The six X_api_check_so run in CI for the first time in this PR: that run is what makes the docs' "CI runs the dlopen drivers" claim true.