feat(margin): M3b buy-in stress mode (deterministic, default-off)

[dayfine]

margin M3b — buy-in stress mode (deterministic stress-path, default-off)

Closes the remaining half of M3 (short-side squeeze robustness) from
dev/plans/levered-longshort-margin-realism-2026-07-14.md. Builds on M3a (#2016).

What it does — the mechanism

Models the worst-case squeeze cost for a levered long-short config: when a short
is hard-to-borrow (HTB), the lender can recall the borrowed shares, forcing a
buy-in. When armed, every held short that is HTB at its current mark is
force-covered at the next weekly (Friday) close — a deterministic upper bound
on buy-in cost for the M4 promotion-grid stress cells.

New pure module Short_buyin (trading/trading/simulation/lib/short_buyin.{ml,mli}),
the short-side mirror of the M2 Long_maintenance runner:

• select_buyins — pure HTB filter over marked short holdings.
• buyin_stress_transitions — Friday-gated TriggerExit builder; each cover is
  tagged StrategySignal { label = "buyin_stress" } at the mark, so forensics
  separate buy-ins from strategy exits, short maintenance covers (margin_call)
  and long reduces (maintenance_reduce).

Deterministic by design

Chose the deterministic stress-path branch over the probabilistic
forced-cover: the M4 grid wants the single worst-case path (every HTB borrow
recalled), not sampled paths, and every analysis function must stay
pure/reproducible (CLAUDE.md). No RNG anywhere — same portfolio + config always
yield the same covers.

HTB definition — dedicated threshold

A short marked strictly below a positive short_buyin_htb_price_below is HTB
(Margin_config.is_buyin_htb ~price). Chose a dedicated threshold over reusing an
M3a tier band because buy-in (share recall) is a distinct broker event from a
maintenance breach — a lender can recall a name comfortably above its maintenance
requirement — so the stress cell's "which shorts get bought in" is decoupled from
the leverage/maintenance dials and the M4 grid can vary them orthogonally. That
low-priced names are the HTB ones mirrors the M3a price-tier philosophy.

R1 (default-off)

Margin_config gains short_buyin_stress_mode : bool [@sexp.default false] +
short_buyin_htb_price_below : float [@sexp.default 0.0]. Placing them on
Margin_config (already threaded to Margin_runner.tick) needs zero new
simulator/panel_runner threading. At the defaults nothing is ever HTB (mode
off, and no positive mark is below 0.0), so tick stays bit-equal — goldens
unchanged, no re-pin.

R2 (searchable)

Both fields resolve through Overlay_validator via the nested margin_config.*
overlay keys; axis-expansion tests test_short_buyin_stress_mode_axis_expands
and test_short_buyin_htb_price_below_axis_expands in test_variant_matrix.ml.

Wiring + collision handling

Margin_runner.tick appends buy-in covers alongside the short force-cover and M2
long-reduce (same Friday cadence + dedup_strategy_exits_for_margin seam). A
short flagged by both the maintenance check and the buy-in mode is covered once —
_drop_buyins_colliding_with_covers keeps the margin_call (richer detail),
drops the duplicate buyin_stress.

Bar-cadence caveat

Documented in short_buyin.mli + the Margin_config field docs: daily-close
marks cannot see an intraweek gap-through-recall; a Monday-to-Thursday squeeze is
only covered at Friday's close — M4 stress-path gap scenarios extend this.

M3a QC drive-bys closed (both non-blocking observations from #2016)

1. Added the symmetric test_short_borrow_rate_tiers_axis_expands (the M3a axis
   was proven only via its structurally-identical short_maintenance_tiers
   sibling).
2. Corrected the borrow-fee disarmed-parity wording from "bit-for-bit" to
   "numerically identical (1e-12)" in portfolio_margin.mli + the renamed
   test_borrow_fee_empty_tiers_numerically_identical_flat. The M3a per-position
   reassociation (Σnᵢ)·r → Σ(nᵢ·r) is not IEEE-bit-identical; goldens hold.

Test plan

• test_short_buyin.ml (8) — R1 default/disarmed no-ops, armed selects only HTB,
  zero-threshold no-op, Friday-armed tagged cover at mark, weekly-cadence Monday
  no-op, unmarked-short skip, no-positions no-op.
• test_margin_accounting.ml (+1 is_buyin_htb gate; round-trip extended to the
  buy-in fields).
• test_variant_matrix.ml (+3 axis-expansion tests).
• Verified green locally: dune build (exit 0), dune build @fmt (clean, no
  diff), dune runtest trading/simulation/test trading/portfolio/test trading/backtest/walk_forward/test (exit 0 — the three suites touching this
  change: portfolio +39, simulation incl test_short_buyin +8, walk_forward
  axis tests), and linter_file_length (exit 0). Magic-number scan of the new
  source is clean (all named constants / semantic zeros; short_buyin.ml has no
  numeric literals). Goldens unchanged (default-off, bit-equal at defaults).
• The full dune runtest + full devtools/checks were CPU-starved by a live
  local sweep chain and not completed locally — CI is authoritative for the
  full surface.

Not in scope

M4 (validation protocol — parity gates, squeeze stress cells, leverage surface
via experiment-gap-closing + confirmation grid). No default flips and no levered
number quoted here.

🤖 Generated with Claude Code

[dayfine]

Reviewed SHA: ef5659f

Structural QC — M3b buy-in stress mode

Hard Deterministic Gates

#	Check	Status	Notes
H1	dune build @fmt	PASS	Format check succeeded (pre-existing doc-comment warnings in unrelated files only)
H2	dune build	PASS	Build succeeded, no errors
H3	dune runtest	CI_AUTHORITATIVE	Full suite timed out after 10min due to container CPU load from concurrent sweep chain; CI is the authoritative linter gate per .claude/rules/pr-merge-gates.md. gh pr checks 2017 shows pending; will PASS once CI completes.

Generic Structural Checks (P1–P5)

#	Check	Status	Notes
P1	Functions ≤ 50 lines (linter)	PASS	short_buyin.ml: 7–37 lines; helper functions well-scoped
P2	No magic numbers (linter)	PASS	All thresholds parameterized through config; no hardcoded tuning constants
P3	Config completeness	PASS	Both new mechanism fields live on Margin_config; no scattered literals
P4	Public-symbol export hygiene (linter)	PASS	Both short_buyin.ml and .mli present; documentation complete
P5	Internal helpers prefixed per convention	PASS	Helpers: _holding_of_position, _priced_short_holdings, _is_friday, _buyin_detail, _buyin_transition — all underscore-prefixed

Project-Specific Architecture Rules (P6, A1–A3)

#	Check	Status	Notes
P6	Tests conform to .claude/rules/test-patterns.md	PASS	test_short_buyin.ml: open Matchers, single assert_that per value, all_of/field composition, no nested matchers. No sub-rule 1/2/3 violations. Tests pin R1 (default-off), R2 (axis expansion), cadence (Friday), exit tags, HTB selection, order preservation.
A1	Core module modifications (Portfolio/Orders/Position/Strategy/Engine)	FLAG	Modified: trading/trading/portfolio/lib/margin_config.{ml,mli} (added short_buyin_stress_mode, short_buyin_htb_price_below fields). Margin_config is NOT on the core watch-list but lives in portfolio/lib. These fields are strategy-agnostic broker-mechanics parameters (per config's own docstring; same pattern as M1b-2, M2, M3a tier tables). This routes to qc-behavioral for generalizability judgment per established margin-seam precedent. FLAG does not block structural APPROVED.
A2	No new analysis/ imports into trading/trading/ outside exceptions	PASS	No analysis/ imports in any PR files; simulation/lib/dune has no analysis dependencies; all imports within trading/trading or stdlib
A3	No unnecessary modifications to existing (non-feature) modules	PASS	13 files: 2 new (short_buyin.ml/.mli), 1 new test, 5 existing directly related to M3b (margin_config, margin_runner, portfolio_margin), 2 existing tests (adding axis expansion tests), 1 status doc, 1 dune update. Zero cross-feature drift.

Experiment Flag Discipline (R1, R2, R3)

R1 — Default-off on merge: Both new config fields carry [@sexp.default ...] with the no-op value:

• short_buyin_stress_mode [@sexp.default false] — mode disarmed by default
• short_buyin_htb_price_below [@sexp.default 0.0] — no positive mark is below 0.0, so nothing is HTB even if mode were on

At defaults, is_buyin_htb always returns false (both conditions must be true). ✓

R2 — An axis the day it lands: Both fields are real Margin_config record fields, searchable via Overlay_validator:

• Axis tests: test_short_buyin_stress_mode_axis_expands, test_short_buyin_htb_price_below_axis_expands in test_variant_matrix.ml ✓

R3 — No default-on without ACCEPT: This PR adds new flags default-off; does not flip any existing defaults. R3 not applicable. ✓

Summary

• H1–H2: Hard gates PASS
• H3: Deferred to CI (authoritative linter gate; currently pending)
• P1–P5: All PASS (verified manually and via CI linters)
• P6: PASS (test patterns verified, no sub-rule violations)
• A1: FLAG (routes to qc-behavioral; established precedent for margin-seam config modifications)
• A2–A3: PASS

Verdict

APPROVED — with A1 FLAG routed to qc-behavioral

Code is structurally sound. The margin-config modification (A1 FLAG) routes to qc-behavioral for generalizability judgment per established margin-seam precedent (M1b-2, M2, M3a). All hard gates pass; H3 deferred to CI which is authoritative for linter suite.

---

CI checks status: gh pr checks 2017

• build-and-test: pending (runs full linter suite)
• perf-tier1-smoke: pending

Merge gate: Do not merge until (1) CI green and (2) qc-behavioral APPROVED.

[dayfine]

Reviewed SHA: ef5659f

Behavioral QC — margin M3b buy-in stress mode

Self-authored PR: verdict posted as an issue comment (cannot --request-changes on own PR). Merge additionally requires CI green + qc-structural APPROVED at tip (the merge executor re-checks).

Contract Pinning Checklist

#	Check	Status	Notes
CP1	Each non-trivial claim in new .mli docstrings has an identified test	PASS	short_buyin.mli: "force-cover every held HTB short at mark on Friday" → test_friday_armed_emits_buyin; "disarmed = no-op / R1" → test_disarmed_friday_no_op + test_default_selects_nothing; "HTB = mark strictly below threshold" → test_armed_selects_only_htb + test_is_buyin_htb_gates_on_mode_and_threshold (boundary price=5.0 → false pinned); "weekly-Friday only" → test_armed_non_friday_no_op; "skips unmarked shorts" → test_unmarked_short_skipped; "exit tag buyin_stress at mark" → _is_buyin_exit matcher in test_friday_armed_emits_buyin. margin_config.mli is_buyin_htb mode/threshold gate → test_is_buyin_htb_gates_on_mode_and_threshold. The one non-trivial claim NOT pinned — the tick-level buy-in↔margin_call collision — is charged under CP4 (it is a modified-.mli guard on tick, not a new-.mli claim).
CP2	Each PR-body "Test plan" claim has a corresponding committed test	PASS	8 test_short_buyin.ml tests (all present); is_buyin_htb gate (test_is_buyin_htb_gates_on_mode_and_threshold); round-trip extended to buy-in fields (test_margin_config_round_trip_preserves_tiers); +3 axis tests (test_short_borrow_rate_tiers_axis_expands, test_short_buyin_stress_mode_axis_expands, test_short_buyin_htb_price_below_axis_expands). No advertised-but-missing test — the body does not claim a dedup/collision test, so CP2 is clean (the gap surfaces under CP4).
CP3	Pass-through / identity / invariant tests pin identity, not just size_is	PASS	R1 no-op tests assert size_is 0 on the transition list — for a mechanism whose only output is the cover set, empty = full identity (not a size_is masking a richer value). Config identity pinned by whole-value equal_to sexp round-trip.
CP4	Each guard called out in code docstrings has a test exercising the guarded scenario	FAIL	Two documented guards are unexercised: (a critical) the buy-in↔maintenance collision guard _drop_buyins_colliding_with_covers — documented in margin_runner.ml and in tick's .mli ("a short flagged by both the maintenance check and the buy-in mode is covered once — the margin_call wins, the duplicate buyin_stress is dropped") — has no test. test_margin_runner.ml was not extended for the buy-in source at all; no test constructs a short that is simultaneously maintenance-breached and HTB on the same Friday. This guard is load-bearing: without it two TriggerExits land on one position in margin_trans and the state machine rejects the second ("Invalid transition") — a crash in exactly the M4 stress cells the module targets. (b minor) _holding_of_position's documented "skips non-short / non-Holding" guard (contract: longs never touched) is untested — every fixture in test_short_buyin.ml is a Holding short; no long marked below the HTB threshold, and no Entering/Exiting short, is passed through buyin_stress_transitions to confirm it is skipped.

Behavioral Checklist (Weinstein S*/L*/C*/T*)

NA — pure margin-realism infrastructure; no stage/screener/stop/domain logic. Spine sanity-check (per weinstein-faithful-core.md): the mechanism only force-covers already-held shorts (Holding filter → TriggerExit); it does not alter which shorts are signaled/entered, and entries remain untouched. W1 spine intact, W2 default-off + config-expressed. A1 (structural FLAG routed here) resolved below.

#	Check	Status	Notes
A1	Margin_config additions + Short_buyin are strategy-agnostic (no Weinstein leak; portfolio layer independent of strategy layer)	PASS	short_buyin_stress_mode / short_buyin_htb_price_below describe broker share-recall (HTB) mechanics — a pure price comparison in is_buyin_htb, no stage/RS/screener state. Margin_config (portfolio lib) references only Short_margin_tiers; it does not import the strategy layer. Short_buyin (simulation lib) is pure (no RNG, no strategy state) and sits above both portfolio and strategy, the established margin seam (M1b-2 #2005, M2 #2010, M3a #2016). No strategy-specific logic leaked into the shared module.

Contract-by-contract (dispatch list)

1. R1 no-op at defaults — PASS. test_default_selects_nothing, test_disarmed_friday_no_op (value-pinned, not just "no error"); is_buyin_htb requires threshold > 0.0 AND stress_mode, so both defaults (false/0.0) yield false. Goldens untouched (PR body; CI authoritative).
2. HTB selection semantics — PASS on selection + boundary. test_armed_selects_only_htb (only sub-threshold CHEAP; RICH untouched; order preserved); test_is_buyin_htb_gates_on_mode_and_threshold pins the boundary side (price=5.0 → false, i.e. strictly-below). Longs-never-touched sub-claim untested — see CP4(b).
3. Cadence (Friday-only) — PASS. test_armed_non_friday_no_op (Monday → empty).
4. Dedup (margin_call wins, covered once) — FAIL (untested). See CP4(a). This is the blocking finding.
5. Exit-tag forensics separability — PARTIAL. buyin_stress tag pinned in isolation (_is_buyin_exit), and the detail string mark=%.6f is distinct from margin_call's entry_avg_cost/current_price. But separability under collision (that the surviving cover is tagged margin_call, not buyin_stress) is unpinned — same gap as CP4(a).
6. R2 axis-expansion, both fields — PASS. Both new-field axis tests present and registered.
7. Worst-case framing honesty — PASS. short_buyin.mli + the Margin_config field docs scope this as a deterministic upper bound ("worst case", "every HTB borrow recalled") and explicitly disclaim intraweek-squeeze realism via the bar-cadence caveat ("cannot observe an intraweek gap-through-recall; a Monday-to-Thursday squeeze is only covered at Friday's close"). Not oversold.
8. A1 FLAG — PASS (see table above).
9. Drive-by closures — PASS. (1) test_short_borrow_rate_tiers_axis_expands added + registered. (2) portfolio_margin.mli reworded "bit-for-bit" → "numerically identically (to within 1e-12)" with the (Σnᵢ)·r → Σ(nᵢ·r) reassociation rationale; test renamed to test_borrow_fee_empty_tiers_numerically_identical_flat with matching comment. Both landed where claimed.

Quality Score

3 — Clean, well-documented, honestly-scoped implementation; R1/R2, HTB boundary, cadence, and tag all pinned. The sole defect is a coverage gap, not a logic error: the newly-introduced buy-in↔margin_call collision guard (a documented, crash-preventing seam) has no test, and test_margin_runner.ml was not extended for the buy-in source.

(Does not affect verdict.)

Verdict

NEEDS_REWORK

NEEDS_REWORK Items

CP4(a): buy-in ↔ margin_call collision guard is untested (blocking)

• Finding: _drop_buyins_colliding_with_covers and the tick .mli's dedup contract ("a short flagged by both the maintenance check and the buy-in mode is covered once — the margin_call wins, the duplicate buyin_stress is dropped") have no exercising test. test_margin_runner.ml was not touched by this PR; no test constructs a short that is both maintenance-breached and HTB on the same Friday. Without this guard two TriggerExits target one position in margin_trans, which the Position.t state machine rejects — a crash in the M4 stress cells this module exists for. The claim "covered once, margin_call wins" is therefore asserted only in prose.
• Location: trading/trading/simulation/lib/margin_runner.ml (_drop_buyins_colliding_with_covers, lines ~100–114; tick, lines ~130–135); .mli dedup paragraph lines ~119–127. No test in trading/trading/simulation/test/test_margin_runner.ml.
• Authority: tick .mli docstring (this PR) + .claude/agents/qc-behavioral.md CP4 (guards named in docstrings must be exercised).
• Required fix: add a tick-level (or Margin_runner) test where one held short is simultaneously maintenance-breached (enabled=true, breaching mark) and HTB (short_buyin_stress_mode=true, mark below threshold) on a Friday; assert the position receives exactly one TriggerExit tagged margin_call (not buyin_stress), and that a distinct HTB-only short in the same tick still receives its buyin_stress cover. This also closes contract 5's under-collision separability gap.
• harness_gap: LINTER_CANDIDATE — deterministic scenario (fixed portfolio + config); a golden/unit test pins it reproducibly.

CP4(b): "longs never touched" / non-Holding skip is untested (minor)

• Finding: _holding_of_position's documented guard ("Skips non-short, non-Holding, and symbols with no mark today") is only partially pinned — test_unmarked_short_skipped covers the no-mark case, but no test passes a long position marked below the HTB threshold (or an Entering/Exiting short) through buyin_stress_transitions to confirm it is skipped. Contract 2's "longs never touched" is thus guarded in code but not pinned.
• Location: trading/trading/simulation/lib/short_buyin.ml _holding_of_position (lines 14–19); trading/trading/simulation/test/test_short_buyin.ml (fixtures are all Holding shorts).
• Authority: short_buyin.ml guard comment + short_buyin.mli ("every held short"); CP4.
• Required fix: add one case in test_short_buyin.ml where the positions map contains a Long marked below the threshold (and optionally a non-Holding short) and assert buyin_stress_transitions emits nothing for them.
• harness_gap: LINTER_CANDIDATE — deterministic fixture-level scenario.

[dayfine]

Reviewed SHA: 532bd86

Behavioral QC (re-review after rework) — margin M3b buy-in stress mode

Self-authored PR: verdict posted as an issue comment (cannot --approve own PR). Merge additionally requires CI green + qc-structural APPROVED at this new tip (the rework added a commit; the merge executor re-checks).

Re-review scope: the test-only rework commit 532bd86d0 (2 files, +174/−3, no production change) addressing the two CP4 gaps from my prior verdict (ef5659f7d). All other rows carry over unchanged (PASS).

The two rework tests pin exactly what the findings demanded

CP4(a) → resolved — test_buyin_collides_with_margin_call (test_margin_runner.ml). Drives the real Margin_runner.tick (not a mock) with an armed+enabled config (_on_config + stress_mode=true, htb_price_below=20.0). COLLIDE (entry $10 / mark $15) is simultaneously maintenance-breached (loss past the $12 cover trigger) and HTB (mark < $20); BUYONLY (entry $10 / mark $5, a profitable short) is HTB-only, not breached. The assertion elements_are [COLLIDE → margin_call; BUYONLY → buyin_stress] pins all three demanded properties: (i) COLLIDE covered exactly once — a double-cover would make the list 3 elements and fail the elements_are count; (ii) the surviving tag is margin_call, not buyin_stress (i.e. _drop_buyins_colliding_with_covers keeps the richer maintenance cover); (iii) a non-colliding HTB short still gets its own buyin_stress cover in the same tick (dedup drops only the collider). This also closes contract 5's under-collision tag-separability gap.

CP4(b) → resolved — test_long_below_threshold_never_covered (test_short_buyin.ml). The position builder is parametrized by side (_make_short retained as a partial application, so every prior fixture is byte-unchanged). A Long marked below the HTB threshold on an armed Friday yields size_is 0 — pinning that _holding_of_position skips non-short positions, i.e. "longs never touched."

Both grounded in production behavior; test-only, no source change, so all APPROVED rows below are unaffected by regression risk.

Contract Pinning Checklist (final)

#	Check	Status	Notes
CP1	New .mli claims pinned	PASS	Carried from prior review: force-cover-on-Friday, R1 no-op, HTB strictly-below boundary, weekly cadence, unmarked-skip, buyin_stress tag, is_buyin_htb gate — all pinned.
CP2	PR-body Test-plan claims all committed	PASS	8 test_short_buyin + is_buyin_htb gate + round-trip + 3 axis tests present; rework added 2 more (now 9 test_short_buyin, 12 test_margin_runner) consistent with the commit message.
CP3	Identity/no-op tests pin identity not just size	PASS	Carried; empty transition-list = full identity for a cover-set output; config identity via whole-value sexp round-trip.
CP4	Docstring-named guards exercised	PASS (was FAIL)	Both previously-unexercised guards now pinned: buy-in↔margin_call collision (test_buyin_collides_with_margin_call) and non-short skip (test_long_below_threshold_never_covered).

Behavioral Checklist (Weinstein S*/L*/C*/T*)

NA — pure margin-realism infrastructure. Spine sanity-check carried: mechanism force-covers only already-Holding shorts, does not alter entry signals; W1 spine intact, W2 default-off + config-expressed.

#	Check	Status	Notes
A1	Margin_config additions + Short_buyin strategy-agnostic; portfolio layer independent of strategy layer	PASS	Carried. Broker HTB/share-recall mechanics only; pure is_buyin_htb price comparison; no strategy import into the portfolio lib; established margin seam (M1b-2 #2005, M2 #2010, M3a #2016).

Quality Score

4 — All checks pass; clean, honestly-scoped implementation. The rework tests are well-constructed: the collision test grounds the dedup in a real tick (not a hand-rolled transition list) and uses elements_are cardinality to prove single-cover, and the long-skip test parametrizes the builder without disturbing existing fixtures.

(Does not affect verdict.)

Verdict

APPROVED

Merge gate reminder: this verdict is behavioral only. Merge additionally requires (1) CI green at 532bd86d0 and (2) qc-structural APPROVED at this tip — the merge executor must re-verify both, since the rework created a new tip after the prior structural approval.

[dayfine]

[Re-pinned at SHA 532bd86 — behavioral-QC rework landed]

Reviewed SHA: 532bd86

Structural verdict STANDS: APPROVED (with A1 FLAG to qc-behavioral).

Second Commit (532bd86): Test-Only Rework — P6 Verified

Changes: +174/−3 lines, 2 test files only; no production-code changes.

New tests:

1. test_buyin_collides_with_margin_call (test_margin_runner.ml, 146 lines)

   • Pins the tick-level dedup contract: short breaching maintenance AND HTB on same Friday emits ONE cover (margin_call wins, duplicate buy-in dropped).
   • Uses: open Matchers, single assert_that with elements_are + _is_exit_tagged helper (proper all_of/field/matching composition).
   • P6 PASS ✓

2. test_long_below_threshold_never_covered (test_short_buyin.ml, 20 lines)

   • Pins the side guard: a LONG marked below HTB threshold never enters buy-in selection (projection skips non-shorts).
   • Refactored _make_short → parametrized _make_position ~side (no breaking change to existing tests).
   • Uses: single assert_that with size_is matcher.
   • P6 PASS ✓

P6 conformance: Both new tests follow proper matcher patterns; no List.exists/unasserted-results/bare-match violations. ✓

All Rows Carry Over

Check	Status	Notes
H1–H2	PASS	Format + build (unchanged from original)
H3	CI_AUTHORITATIVE	Deferred to CI (unchanged)
P1–P5	PASS	Linters cover (unchanged)
P6	PASS	Test patterns verified on second commit (+2 tests, all conformant)
A1–A3	PASS / FLAG	Margin_config FLAG (unchanged) + A2–A3 PASS (only tests added)
R1–R3	PASS	Experiment discipline (unchanged)

Verdict

APPROVED at 532bd86 — behavioral-QC rework adds conformant test coverage. All structural constraints met.

---

Merge gate: (1) CI green, (2) qc-behavioral APPROVED (already signaled per coordinator).