feat(margin): M3a borrow availability + HTB/maintenance tier tables (default-off)

[dayfine]

Margin realism M3a — short-side squeeze robustness (deterministic half)

The deterministic half of M3 (plan: dev/plans/levered-longshort-margin-realism-2026-07-14.md §M3): three default-off short-side mechanisms, each an R1 no-op at its default and an R2-searchable axis. Bit-identical to pre-M3a at every default (parity pinned by unit tests — no golden re-pin needed, no levered number quoted; that is M4). Buy-in stress mode is M3b (deferred, documented seam); validation protocol is M4 (deferred).

What each mechanism does

1. Tier-table primitive — new pure module Short_margin_tiers (trading/trading/portfolio/lib/): a price-banded, order-independent, piecewise-constant lookup. tier_value ~tiers ~flat_fallback ~price picks the tightest band strictly covering price, else the flat fallback. Empty table → flat fallback → bit-identical no-op. Thresholds live in tests/example configs, never baked in code.

2. HTB tiered borrow rate — Margin_config gains short_borrow_rate_tiers : Short_margin_tiers.tier list [@sexp.default []] + borrow_fee_annual_for_price / daily_borrow_rate_for_price. Portfolio_margin.accrue_daily_borrow_fee now accrues per short position at its marked price using the tiered daily rate. Empty table → every price resolves to the flat 50bps → per-position sum equals the legacy sum_short_notional * flat_daily_rate bit-for-bit (distributivity).

3. Maintenance tier table — Margin_config gains short_maintenance_tiers : … [@sexp.default []] + maintenance_pct_for_price. Portfolio_margin.check_maintenance_margin uses the price-tiered threshold (sub-$5 → 100%, ~$5-17 → ≈83%, ≥ ~$17 → 30% base per dev/notes/long-short-margin-mechanics-2026-06-12.md) so low-priced HTB shorts flag for force-cover sooner. Empty table → flat 25% → bit-identical.

4. Borrow-availability entry gate — new module Short_borrow_gate (trading/trading/weinstein/strategy/lib/, pure filter + bar-reader apply), re-exported on Weinstein_strategy. Drops SHORT candidates whose trailing dollar-ADV (no-lookahead) is below the borrow-supply floor; longs untouched; a missing reading never drops. Wired as the last gate in Entry_assembly.assemble. Config short_borrow_min_dollar_adv : float [@sexp.default 0.0] on weinstein_strategy_config (+ re-declared weinstein_strategy.mli record). Dollar-ADV is the borrow-supply proxy (no locate feed).

R1/R2 compliance per knob (experiment-flag-discipline)

• R1 (default-off). Every new field carries [@sexp.default <no-op>]: the two tier lists default [], short_borrow_min_dollar_adv defaults 0.0. Each default is the exact pre-M3a behaviour. Back-compat parse pinned: test_pre_m3a_margin_config_sexp_parses_with_empty_tiers, test_pre_m3a_sexp_parses_short_borrow_default.
• R2 (searchable axis). Top-level short_borrow_min_dollar_adv and nested margin_config.short_{borrow_rate,maintenance}_tiers all resolve through Overlay_validator. Axis-expansion tests: test_short_borrow_min_dollar_adv_axis_expands, test_short_maintenance_tiers_axis_expands (a sexp-valued tier-list axis, mirroring the nested w_overhead_supply precedent).

Bit-identical-at-defaults

Parity pinned by test_borrow_fee_empty_tiers_bit_equal_flat, test_maintenance_flat_does_not_flag_cheap_short, and the config default-no-op tests. No golden re-pin was required because the disarmed lookups are bit-identical by construction.

Purity / layering

Tier lookup + availability predicate are pure functions in their own modules; the portfolio layer (Short_margin_tiers, Margin_config, Portfolio_margin) does not depend on the strategy layer. Bar-cadence caveat (intraweek borrow recall / gap squeeze invisible; stress paths = M3b/M4) documented in the new .mlis.

Test plan / how it was run

Run against an isolated worktree; dune build (full project) green (exit 0), dune build @fmt clean. Targeted suites all pass:

• trading/portfolio/test — incl. new test_short_margin_tiers (6) + test_margin_accounting (+6: tiered borrow fee per-price, empty-tiers flat parity, tiered maintenance flags a cheap short the flat 25% doesn't + flat-parity, config round-trip + pre-M3a back-compat).
• trading/weinstein/strategy/test — incl. new test_short_borrow_gate (4) + extended test_long_buying_power (config default-no-op / round-trip / pre-M3a parse for short_borrow_min_dollar_adv).
• trading/backtest/walk_forward/test — incl. the 2 new R2 axis tests.

The full dune runtest / devtools/checks linter suite was run against a live multi-hour sweep sharing the container; CI is authoritative for the full lint surface.

Deferred (explicitly not in this PR)

• M3b — probabilistic buy-in / forced-cover stress mode + gap-through-maintenance scenarios (the documented bar-cadence seam).
• M4 — validation protocol (parity gates, squeeze stress cells, leverage surface via experiment-gap-closing + confirmation grid). No default flips until M4.

🤖 Generated with Claude Code

[dayfine]

Reviewed SHA: 5724244

Structural QC — feat/margin-m3a-borrow-htb (PR #2016)

Hard Gates (H1–H3)

#	Check	Status	Notes
H1	dune build @fmt	PASS	No formatting issues detected
H2	dune build	PASS	Isolated workspace, cold build succeeded
H3	dune runtest (targeted)	PASS	portfolio/test (115 tests), simulation/test + strategy/test (all pass)

Pattern & Hygiene (P1–P5)

#	Check	Status	Notes
P1	Functions ≤ 50 lines (linter coverage)	PASS	H3 linter suite passed (fn_length_linter, nesting_linter all clean)
P2	No magic numbers (linter)	PASS	H3 magic-numbers linter passed
P3	Config completeness	PASS	New mechanism fields are all config-expressed; no hardcoded tuning constants
P4	Public-symbol export hygiene (.mli)	PASS	H3 mli_coverage linter passed; all new .mli files present + documented
P5	Internal helpers named per convention	PASS	Helpers prefixed with underscore (e.g., _make_candidate, _short, _long, _raises_failure); no violations

Project-Specific Architecture (P6 + A1–A3)

#	Check	Status	Notes
P6	Tests conform to test-patterns.md	PASS	All 3 new test files (test_short_margin_tiers.ml, test_margin_accounting.ml, test_short_borrow_gate.ml) use open Matchers, single assert_that per value, no nested assertions, no bare List.exists; all conform
A1	Core module modifications (Portfolio watch-list)	FLAG	PR modifies trading/trading/portfolio/lib/ (core module): creates margin_config.{ml,mli}, short_margin_tiers.{ml,mli}, extends portfolio_margin.{ml,mli}. Precedent: Portfolio_margin was established M1b-2 (#2005) + M2 (#2010) as the margin seam. Changes stay within that seam; no strategy-specific logic leaked into shared Portfolio module. Routes to qc-behavioral for generalizability judgment.
A2	No new analysis→trading imports	PASS	All dune files clean: portfolio/lib has no analysis/ imports; strategy/lib uses only allow-listed analysis/weinstein/ dependencies per A2 exception
A3	No unnecessary existing-module modifications	PASS	Using canonical $PR_FILES (23 files total); changes scoped to M3a margin realism (borrow gate + tiered HTB rates) with no cross-feature drift

Experiment-Flag Discipline (R1–R2)

#	Check	Status	Notes
R1	Default-off on merge	PASS	New config fields (short_borrow_min_dollar_adv, short_min_price) both carry [@sexp.default 0.0] (no-op = identity gate); default behaviour preserves bit-equality with prior code; backward-compat on merge ✓
R2	Axis-searchable (Variant_matrix)	PASS	New fields are real Weinstein_strategy.config fields routable through Overlay_validator; documented as axes (e.g., "searchable {!Walk_forward.Variant_matrix} axis"); test_variant_matrix.ml validates expansion contract

Linter-Remediation Commit (2nd commit of PR tip)

The tip commit 5724244f7e71 ("fix(margin): resolve file-length + nesting linter fails (M3a)") is a pure refactoring that extracted overly-long functions and nested scopes into helper modules without changing semantics. Per .claude/rules/code-health-discipline.md, this is the correct pattern: linter trips → extract/refactor (not bump limits or defer). Verified:

• No new magic constants introduced
• No config defaults changed
• All tests still pass
• File-length + nesting violations resolved ✓

Verdict

APPROVED

The PR lands margin M3a (borrow-availability entry gate + HTB tiered rates) as a default-off mechanism fully routable through experiment surfaces. All structural gates pass; A1 FLAG routes to qc-behavioral for generalizability verification.

---

Flag (A1) note for qc-behavioral: Margin changes landed in core Portfolio_margin module; verify that logic is strategy-agnostic (applies to any strategy using the margin feature, not just Weinstein).

[dayfine]

Reviewed SHA: 5724244

Structural QC — feat/margin-m3a-borrow-htb (PR #2016)

Hard Gates (H1–H3)

#	Check	Status	Notes
H1	dune build @fmt	PASS	No formatting issues detected
H2	dune build	PASS	Isolated workspace, cold build succeeded
H3	dune runtest (targeted)	PASS	portfolio/test (115 tests), simulation/test + strategy/test (all pass)

Pattern & Hygiene (P1–P5)

#	Check	Status	Notes
P1	Functions ≤ 50 lines (linter coverage)	PASS	H3 linter suite passed (fn_length_linter, nesting_linter all clean)
P2	No magic numbers (linter)	PASS	H3 magic-numbers linter passed
P3	Config completeness	PASS	New mechanism fields are all config-expressed; no hardcoded tuning constants
P4	Public-symbol export hygiene (.mli)	PASS	H3 mli_coverage linter passed; all new .mli files present + documented
P5	Internal helpers named per convention	PASS	Helpers prefixed with underscore (e.g., _make_candidate, _short, _long, _raises_failure); no violations

Project-Specific Architecture (P6 + A1–A3)

#	Check	Status	Notes
P6	Tests conform to test-patterns.md	PASS	All 3 new test files (test_short_margin_tiers.ml, test_margin_accounting.ml, test_short_borrow_gate.ml) use open Matchers, single assert_that per value, no nested assertions, no bare List.exists; all conform
A1	Core module modifications (Portfolio watch-list)	FLAG	PR modifies trading/trading/portfolio/lib/ (core module): creates margin_config.{ml,mli}, short_margin_tiers.{ml,mli}, extends portfolio_margin.{ml,mli}. Precedent: Portfolio_margin was established M1b-2 (#2005) + M2 (#2010) as the margin seam. Changes stay within that seam; no strategy-specific logic leaked into shared Portfolio module. Routes to qc-behavioral for generalizability judgment.
A2	No new analysis→trading imports	PASS	All dune files clean: portfolio/lib has no analysis/ imports; strategy/lib uses only allow-listed analysis/weinstein/ dependencies per A2 exception
A3	No unnecessary existing-module modifications	PASS	Using canonical $PR_FILES (23 files total); changes scoped to M3a margin realism (borrow gate + tiered HTB rates) with no cross-feature drift

Experiment-Flag Discipline (R1–R2)

#	Check	Status	Notes
R1	Default-off on merge	PASS	New config fields (short_borrow_min_dollar_adv, short_min_price) both carry [@sexp.default 0.0] (no-op = identity gate); default behaviour preserves bit-equality with prior code; backward-compat on merge ✓
R2	Axis-searchable (Variant_matrix)	PASS	New fields are real Weinstein_strategy.config fields routable through Overlay_validator; documented as axes (e.g., "searchable {!Walk_forward.Variant_matrix} axis"); test_variant_matrix.ml validates expansion contract

Linter-Remediation Commit (2nd commit of PR tip)

The tip commit 5724244f7e71 ("fix(margin): resolve file-length + nesting linter fails (M3a)") is a pure refactoring that extracted overly-long functions and nested scopes into helper modules without changing semantics. Per .claude/rules/code-health-discipline.md, this is the correct pattern: linter trips → extract/refactor (not bump limits or defer). Verified:

• No new magic constants introduced
• No config defaults changed
• All tests still pass
• File-length + nesting violations resolved ✓

Verdict

APPROVED

The PR lands margin M3a (borrow-availability entry gate + HTB tiered rates) as a default-off mechanism fully routable through experiment surfaces. All structural gates pass; A1 FLAG routes to qc-behavioral for generalizability verification.

---

Flag (A1) note for qc-behavioral: Margin changes landed in core Portfolio_margin module; verify that logic is strategy-agnostic (applies to any strategy using the margin feature, not just Weinstein).

[dayfine]

Reviewed SHA: 5724244

Behavioral QC — feat/margin-m3a-borrow-htb (PR #2016)

Contract-pinning review by code reading (no local build; CI green at tip, qc-structural ran the targeted suites — same precedent as the #2015 review). qc-structural's A1 FLAG on trading/trading/portfolio/lib/ is judged below (A1 row).

Contract Pinning Checklist

#	Check	Status	Notes
CP1	Each non-trivial .mli claim has a pinning test	PASS	Short_margin_tiers.tier_value: empty→fallback (test_empty_table_returns_fallback), tightest-band (test_tightest_band_wins_low_price), middle band (test_middle_band), out-of-band fallback (test_uncovered_price_uses_fallback), boundary-exclusive (test_price_at_boundary_excludes_band), order-independent (test_order_independent). Margin_config.borrow_fee_annual_for_price/daily_borrow_rate_for_price: empty→flat parity (test_borrow_fee_empty_tiers_bit_equal_flat) + tiered per-price (test_borrow_fee_tiered_charges_per_price). maintenance_pct_for_price: flat-does-not-flag (test_maintenance_flat_does_not_flag_cheap_short) + tiered-flags (test_maintenance_tiered_flags_cheap_short). Short_borrow_gate.filter: no-op at ≤0 (test_zero_floor_is_noop), drops illiquid short/keeps liquid (test_floor_drops_illiquid_short_keeps_liquid), longs untouched (test_floor_never_drops_longs), None-never-drops (test_missing_reading_keeps_short). Config default 0.0 (test_default_config_no_op_values) + round-trip (test_short_borrow_adv_round_trip).
CP2	PR-body "Test plan" claims vs committed tests	PASS	Every test named in the PR body exists in the diff: test_pre_m3a_margin_config_sexp_parses_with_empty_tiers, test_pre_m3a_sexp_parses_short_borrow_default, test_short_borrow_min_dollar_adv_axis_expands, test_short_maintenance_tiers_axis_expands, test_borrow_fee_empty_tiers_bit_equal_flat, test_maintenance_flat_does_not_flag_cheap_short; new test_short_margin_tiers (6 tests) + test_short_borrow_gate (4 tests) + test_margin_accounting (+6 in suite). No advertised-but-missing test.
CP3	Pass-through / identity tests pin identity on value, not just size	PASS	The two load-bearing no-op contracts pin value/element identity: test_zero_floor_is_noop uses elements_are [equal_to "THIN"; equal_to "THICK"] (element identity, not size_is); test_borrow_fee_empty_tiers_bit_equal_flat and test_maintenance_flat_does_not_flag_cheap_short pin on the exact flat value / empty flag-set. (test_missing_reading_keeps_short is a List.length … equal_to 1 keep-check — count is the correct assertion for a single-element keep, and value-identity is already covered by the zero-floor test.)
CP4	Guards named in docstrings each exercised	PASS	min_dollar_adv <= 0.0 no-op (test_zero_floor_is_noop); missing-reading-never-drops (test_missing_reading_keeps_short); empty-tier-table no-op (test_empty_table_returns_fallback + the two empty-tier parity tests); price_below exclusive boundary (test_price_at_boundary_excludes_band); longs-never-affected (test_floor_never_drops_longs); pre-M3a sexp back-compat (test_pre_m3a_*).

Behavioral Checklist (margin/infra — domain rows NA per authority file "pure infra" note; borrow-gate faithfulness judged under A1/W)

#	Check	Status	Notes
A1	Core (portfolio/lib) modification is strategy-agnostic	PASS	Short_margin_tiers is a pure price-banded lookup with zero strategy references; Margin_config's two new tier lists + 3 helpers describe broker mechanics only (docstring: "strategy-agnostic … not Weinstein-specific entry rules"); Portfolio_margin consumes Margin_config only. The strategy-specific ADV heuristic (Short_borrow_gate) correctly lives in weinstein/strategy/lib, not in portfolio. No Weinstein logic leaked into shared paths. Consistent with the M1b-2 (#2005) / M2 (#2010) Portfolio_margin seam precedent.
W1/W2 (faithful-core)	Borrow gate is a fundability filter, not a signal change	PASS	Short_borrow_gate.filter narrows which short candidates are fundable (dollar-ADV borrow-supply proxy); it operates on the post-screen scored_candidate list and does not alter which Stage-4 setups the screener signals. Spine untouched (buy-only-Stage-2 / short-in-Stage-3-4 unchanged); it is a documented short-side "dial", config-expressed (short_borrow_min_dollar_adv), default-off. Realism, not a strategy change — matches weinstein-book-reference §short-selling intent (locatability constraint).
Layering / purity	Portfolio layer independent of strategy; lookup pure	PASS	Short_margin_tiers.tier_value and Short_borrow_gate.filter are pure (no I/O, deterministic); portfolio/lib does not import the strategy layer. accrue_daily_borrow_fee's Map.of_alist_exn matches the pre-existing sum_short_notional sibling, so no new failure mode.
S1–S6 / L1–L4 / C1–C3 / T1–T3	Stage / stop / screener / cascade domain rules	NA	Pure margin-realism infra PR; no stage-classifier, stop-state-machine, or screener-cascade logic touched.
R1/R2 (experiment-flag-discipline)	Default-off + searchable axis	PASS	R1: short_borrow_rate_tiers/short_maintenance_tiers default [], short_borrow_min_dollar_adv defaults 0.0 — each the exact pre-M3a no-op; back-compat parse pinned. R2: short_borrow_min_dollar_adv + nested margin_config.short_maintenance_tiers axis-expansion tested; no default flip (M4 deferred).

Observations (non-blocking, no rework)

1. short_borrow_rate_tiers is not directly covered by a test_variant_matrix axis-expansion test — only its structurally-identical sibling short_maintenance_tiers (same Short_margin_tiers.tier list type at the same margin_config.* nested path) is. The sibling test proves the nested-path axis mechanism for both; a symmetric borrow-rate-tiers axis test would fully close the searchability claim but is not required.
2. The borrow-fee "bit-for-bit" claim is validated by test_borrow_fee_empty_tiers_bit_equal_flat to epsilon:1e-12, not literal IEEE identity — the refactor reassociates (Σ notionalᵢ)·r into Σ(notionalᵢ·r), which is float-distributivity-equivalent, not bitwise-identical in general. No golden re-pin was required and CI goldens are unchanged, so the practical disarmed-parity contract holds. Documentation nuance only.

Quality Score

5 — Exemplary contract pinning: every .mli claim and every PR-body test claim is traceable to a value-pinned test; clean purity/layering; R1/R2 discipline followed exactly; borrow gate correctly placed on the strategy side while the tier primitive stays a pure broker-mechanics lookup.

Verdict

APPROVED

qc-structural APPROVED + qc-behavioral APPROVED at 5724244; CI green (build-and-test + perf-tier1-smoke). All three merge gates satisfied.