docs(fiqh): the venue boundary is closed; what is open is the premise underneath it - #672
Merged
Conversation
… underneath it #669 landed an open question that #667 and #668 then closed, and the merge order let all three through without a conflict. The bullet still said a SELL is never clamped, `filled_quantity` is recorded nowhere, and no sweep cancels a bracket whose position is gone -- three claims that are now false in the same file that describes the machinery making them false. It is replaced by the fact that actually remains open, and it is a better question than the one it retires. `_clamp_to_held`, rail 21 and `sweep_orphan_brackets` all fail OPEN on an unreadable balance -- deliberately, since refusing a SELL over a quiet endpoint would strand positions that wanted out -- so a venue that stops answering does not produce a refusal, it produces the old behaviour. That is survivable only while the account cannot go short, and nothing checks that: `verify_cash_account` exists on the Alpaca adapter alone. The layered defence is sound whenever the venue answers, and rests on an unverified premise whenever it does not (#666). THE PIN THAT FAILED TO FIRE, since the lesson is the durable part. #669 anchored this section to `_sell_base_size`'s docstring sentence, on the theory that #667 landing would break it and force the doc forward with the code. It did not: #667 clamped at intent construction and left that docstring standing, so the pin held while the paragraph it guarded went stale. A proxy is only a pin while the thing it stands for and the thing it matches move together, and that one stopped. Re-anchored two-sided against the coinbase adapter having no posture read and the alpaca adapter still having one -- the actual premise, not a sentence about it. When #666 lands, this fails because the fact changed. 4 mutants, 4 killed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NzuKAe2RVrPt9acVAWjRyL
This was referenced Sep 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #669/#670/#671, which all merged cleanly and left
docs/fiqh-basis.mdinternally inconsistent.What was wrong
#669 landed a "Known open questions" bullet describing the venue-boundary gap. #670 and #671 then closed it. Git merged all three without a conflict, so the doc now claims — three paragraphs below the section describing the machinery that fixes it — that:
_clamp_to_held)filled_quantityis recorded nowhere on this deployment (now written before the price guard)sweep_orphan_brackets)The pin that failed to fire
This is the part worth recording. #669 anchored that section to
_sell_base_size's docstring sentence — "it can only ever make an exit MORE likely to be accepted" — reasoning that #667 landing would break it and force the doc forward with the code.It didn't. #667 clamped at intent construction and left that docstring standing, correctly, because the function's own contract never changed. So the pin held while the paragraph it guarded went stale.
A proxy is only a pin while the thing it stands for and the thing it matches move together. That one stopped, silently, and the test stayed green through exactly the change it existed to catch.
What replaces it
The question that actually remains open, and it is a better one than the bullet it retires.
_clamp_to_held, rail 21 andsweep_orphan_bracketsall fail open on an unreadable balance — deliberately and correctly, since refusing a SELL over a balance endpoint that went quiet would strand positions that wanted out. So a venue that stops answering does not produce a refusal; it produces the old behaviour, an exit sized from keel's own ledger.That is survivable only while the account cannot go short, and keel does not check that it cannot.
verify_cash_accountexists on the Alpaca adapter alone. The layered defence is sound whenever the venue answers, and rests on an unverified premise whenever it does not — which is #666.Re-anchored
Two-sided against the premise itself rather than a sentence about it: the coinbase adapter must still have no posture read, and the alpaca adapter must still have one. When #666 lands, this test fails because the fact changed, not because someone reworded a paragraph.
4 mutants, 4 killed. Full suite: 5109 passed, 3 skipped. ruff and mypy clean.