ADR 0006: Broker failures as a Result at the port and use-case boundary¶
- Status: Accepted
- Date: 2026-11-11
Context¶
After step 4 (ADR 0005), a broker
failure was an exception. It travelled from the TradeLocker client through
the Broker adapter and the ExecuteSignal use case to the webhook thread.
Nothing in a signature said that any of the five broker calls could fail. A
caller could forget the failure without any sign until production.
Roadmap step 4b makes the failure a value at the boundary. It is a structure
step: ADR 0001's equivalence rule applies, and tests/characterization stays
unchanged. Step 2f pinned a failure at every broker call first. Those pins
check the calls made, the console lines, the lock release, and that the
handler re-raises the client's own exception object.
Decision¶
Resultin the domain.tradelocker_bot.domain.resultdefinesOk(value),Err(error)andResult = Union[Ok[T], Err[E]], as frozen dataclasses. It lives in the domain because the domain is the only layer every other layer may import; step 3's validation will return it too. Callers branch withisinstanceormatch. A result refuses truth testing (bool()raisesTypeError).Ok(0)andOk(None)would otherwise be truthy, andwhile not order_id:on an unwrapped result would stop retrying silently.- Broker port. Every
Brokermethod returnsResult[T, BrokerFailure].BrokerFailure(cause)holds the client's exception object as raised. - Adapter.
TradeLockerBrokerturns anyExceptionfrom a client call intoErr(BrokerFailure(error)). Only the client call is wrapped: the adapter's own handling of the answer (reading the balance field, counting rows) stays outside, so a bug there raises instead of posing as a broker outage. The client raises its ownTLAPIException, a bareValueErrorfor an unknown symbol, and whateverrequestsand pandas raise underneath, so no narrower list is complete.BaseException(interrupts, interpreter exit) is not caught. - Use case.
ExecuteSignal.executereturnsOk(None), or the first broker failure at once. It makes no further broker call and writes nounlockedline, exactly where the exception used to leave. -
Legacy delegate.
handle_position_normalraisesresult.error.causeinside the lock. That is the same object, so the webhook thread fails with the same type, message and attributes as before.The traceback is not the same. It still runs from the delegate down through the client to the raise site, but the use-case frames in between are gone, because the exception left them as a value. ADR 0001's equivalence rule covers type and outcome, not frames. The cost is diagnostic: a failed instrument lookup no longer shows whether it was the first or the second one. Logging the failure inside the use case would recover that, and belongs with failure reporting in step 5.
Update: step 5 (ADR 0010) was a structure step, so it moved the re-raise into
SignalHandler.handleunchanged. Failure logging and reporting moved to step 6.
Kept out of the Result in this step¶
- Lot and inversion errors (
ValueError,ZeroDivisionError, and theTypeErrorfrom a missing balance) still raise from the domain. They are input validation. Turning them into values here would mean catchingTypeErrorandZeroDivisionErroraround domain calls, which would also hide real bugs. Step 3 validates the whole signal before any broker call and returns its own Result. - The console port still returns
None. The only way writing to stdout can fail is an infrastructure fault the use case cannot handle (a closed pipe). A Result there would add a branch to every line, with no recovery to put in it. If the console becomes a remote sink, its port gets a Result then.
Consequences¶
- Every broker call's failure is visible in its signature. The type checker and the unit tests can follow each one.
- The use case's unit tests check, for an
Errat every port call, the exact calls and lines before it. They also check that the returned failure holds the original exception. -
Behaviour is unchanged. The webhook thread still dies with the client's exception. Reporting failures to the operator instead is a behaviour change for step 5 or 6.
Update: step 6. Step 5 (ADR 0010) changed structure only. -
execute's return type covers broker failures only. Until step 3, invalid input (a malformed lot, an unknownisInvert, a missing balance) still raises from the use case, after any positions were already closed in theisInvertcase. A caller that stops re-raising, such as step 5's inbound adapter, must therefore come after step 3 or keep handling those exceptions.Update: step 3 (ADR 0008) removed every input error from the use case. The missing balance still raises until step 3b, so step 5 follows 3b.
Update: step 3b (ADR 0009) refuses the missing balance, the unknown symbol and the unusable quantity as
Err(Refusal). No signal and no well-formed broker answer raises from the use case any more, so step 5 can start. An answer the adapter cannot read still raises, on purpose.executenow returnsResult[None, BrokerFailure | Refusal]. The legacy handler re-raises only aBrokerFailureand prints a refusal.Update: step 6i (ADR 0021) returns an order the broker answered without creating as
Err(OrderRejected), not as aBrokerFailure. The use case reports it and printsunlockedbefore returning it, since its handling ends normally.executenow returnsResult[None, BrokerFailure | Refusal | OrderRejected]. A broker call that gets no answer is still aBrokerFailureand still raises.
Alternatives considered¶
- A third-party Result library (
returns,result). Rejected: the layer rule admits no third-party package in the domain, and two dataclasses cover what is needed. - Re-raise a new exception in the delegate (
raise BrokerError(...) from cause). Rejected: it changes the type the thread dies with, which the pins forbid in a structure step. - Catch only
TLAPIExceptionin the adapter. Rejected: an unknown symbol and network errors would still escape as exceptions, so the port's signature would make a promise the adapter does not keep.