chore(tot): L-7b-ii monolithic libtotapi_mono.so PoC

[k-yoshimi]

Summary

Time-boxed PoC adding a libtotapi_mono.so Makefile target that links eq + tr + fp + ti + wrx PIC objects into ONE shared image with a SINGLE canonical BPSD broker. Foundation work toward activating the ('eq','tr') BPSD coupling rule deferred in L-7b-ii §0.

Follow-up: #201

Background

Independent Codex review identified that the L-7b-ii spec §0's premise — "libtotapi.so co-links eq + tr + bpsd into one image" — is incorrect for the actually shipped artifact:

$ otool -L tot/libtotapi.so | grep api
    @rpath/libeqapi.so
    @rpath/libtrapi.so
    @rpath/libfpapi.so
    @rpath/libtiapi.so
    @rpath/libwrxapi.so

$ nm tot/libtotapi.so | grep '_bpsd_.*_MOD_.*x_init_flag'
(empty — libtotapi.so carries no bpsd storage of its own)

So today's libtotapi.so has the same per-.so BPSD isolation that TotPipeline would, just hidden by the test fixtures not exercising the broker round-trip. The Codex recommendation was to build a true monolithic image. This PoC validates that.

What works (verified)

• Build: make -C tot libtotapi_mono.so succeeds on macOS arm64.
• BPSD dedup: nm libtotapi_mono.so | grep '_bpsd_.*_MOD_.*x_init_flag' | sort -u shows exactly 8 unique symbols (one per bpsd module type), not 5×8.
• No per-module .so deps: otool -L libtotapi_mono.so shows only libgfortran, libquadmath, libSystem.
• C ABI surface preserved: 6 tot_* exports present (init / run / get_state / set_param / set_param_str / finalize).
• Default libtotapi.so path untouched: zero risk of regression in existing equivalence tests.
• libtotapi_mono_inspect target hard-fails if bpsd dedup ever drifts (count != 8).

What's deferred

libtotapi_mono.so is not yet dlopen-loadable through Python ctypes — ~30 graphics symbols unique to specific per-module <mod>_graphics_stubs.o files (_getkgt_, _getkrt_, _contX_, _r2w2b_, _text_, _move_, ...) stay undefined at dlopen time. The mono build keeps only ONE per-module stub set (fp's, broadest non-conflicting) to avoid duplicate-symbol link errors, but no single set covers all modules' unique symbols.

The fix is a unified tot/tot_graphics_stubs_mono.f90 consolidating the ~60-symbol union. Tracked at #201.

Reviewer trail

• In-house code reviewer: SHA e82e1179 → 2 MED + 3 LOW (wildcard parse-time, follow-up issue not filed, clean target). All addressed in amend 53c4978a. Delta re-review: approve, ship.
• Codex rescue: SHA e82e1179 → "hold" citing wildcard blocker + spec §0 phrasing + inspect count check. All technical blockers addressed in amend 53c4978a. Delta re-review: resolved. (Note: Codex's time-boxing concern was a user-level scope decision, not a technical blocker.)

Test plan

• make -C tot libtotapi_mono.so builds cleanly
• make -C tot libtotapi_mono_inspect shows 8 unique bpsd storage symbols + no per-module .so deps + all 6 tot_* exports
• Default libtotapi.so path unchanged (make -C tot libtotapi.so still works)
• Sanity-guard fires if PIC obj/pic/ trees are absent (added in amend after reviewer feedback)
• Equivalence test against mono: deferred to follow-up (graphics stubs gap)
• Layer-C BPSD smoke test: deferred to follow-up

🤖 Generated with Claude Code

---

Note

Medium Risk
Build-system changes introduce a new shared-library link path that co-links many module PIC objects and changes PIC cleanup; risk is mainly around linker/ABI/regression in alternative build workflows, though the default libtotapi.so path remains unchanged.

Overview
Adds an opt-in monolithic shared library target, libtotapi_mono.so, that co-links eq/tr/fp/ti/wrx PIC objects into a single image with a single deduplicated BPSD object set (enabling future cross-module BPSD broker coupling in one runtime).

Updates tot/Makefile to build/inspect the mono artifact (guards against empty wildcards, omits duplicate graphics stubs, sets distinct install_name/soname, and adds libtotapi_mono_inspect), and extends clean_pic to remove libtotapi_mono.so.

Adds a new spec note, 2026-05-14-l7b-ii-monolithic-poc-findings.md, documenting that current libtotapi.so is not monolithic, what the PoC proves, and the remaining blocker (unified graphics stubs for dlopen/equivalence tests).

^{Reviewed by Cursor Bugbot for commit 1825307. Bugbot is set up for automated code reviews on this repo. Configure here.}

[k-yoshimi]

@cursor review

[k-yoshimi]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 1825307. Configure here.}