Skip to content

docs(fiqh): the venue boundary is closed; what is open is the premise underneath it - #672

Merged
eaitbrahim merged 1 commit into
mainfrom
reconcile-fiqh
Sep 1, 2026
Merged

docs(fiqh): the venue boundary is closed; what is open is the premise underneath it#672
eaitbrahim merged 1 commit into
mainfrom
reconcile-fiqh

Conversation

@eaitbrahim

Copy link
Copy Markdown
Contributor

Follow-up to #669/#670/#671, which all merged cleanly and left docs/fiqh-basis.md internally 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:

  • a SELL is never clamped to the account's holding (now false — _clamp_to_held)
  • filled_quantity is recorded nowhere on this deployment (now written before the price guard)
  • no sweep cancels a SELL whose position is gone (now false — 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 and sweep_orphan_brackets all 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_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 — 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.

… 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
@eaitbrahim eaitbrahim self-assigned this Sep 1, 2026
@eaitbrahim
eaitbrahim merged commit 97b56f4 into main Sep 1, 2026
4 checks passed
@eaitbrahim
eaitbrahim deleted the reconcile-fiqh branch September 1, 2026 12:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant