interfaces: split PollResultCode into generator verdict and orthogonal fill overlay

[mfw78]

Problem

PollResultCode conflates the generator's verdict (should a discrete order be posted?) with observed fill state (PARTIALLY_FILLED / FILLED). The two fill variants can never be returned by any handler's poll(); they are synthesised only by ComposableCoW after poll() returns SUCCESS. The conflation also forces a false choice between "postable" and "partially filled", which is the root of the partiallyFillable stranding bug.

Current

src/interfaces/IConditionalOrder.sol L71-90 defines a seven-variant PollResultCode and a PollResult carrying filledAmount. BaseConditionalOrder.poll (L37-57) and all five order types only ever emit SUCCESS / WAIT_TIMESTAMP / WAIT_BLOCK / TRY_NEXT_BLOCK / INVALID; PARTIALLY_FILLED / FILLED and a non-zero filledAmount are produced only in ComposableCoW.getTradeableOrderWithSignature (L167-185). checkOrder likewise declares a return space it cannot produce.

Proposed

Split into a handler-facing verdict enum, for example GeneratorResultCode { POST, WAIT_TIMESTAMP, WAIT_BLOCK, TRY_NEXT_BLOCK, INVALID } returned by poll(), and an orthogonal fill overlay (for example FillStatus { NONE, PARTIALLY_FILLED, FILLED } plus filledAmount) composed into the public PollResult by ComposableCoW. Handlers lose the unreachable variants and the dead filledAmount field; fill state gains a place that can coexist with a POST verdict, which is what lets a partially filled partiallyFillable order keep being posted.

Scope

src/interfaces/IConditionalOrder.sol, src/BaseConditionalOrder.sol, src/ComposableCoW.sol, the checkOrder return type, tests, and docs. All five order types are unchanged (they never used the fill half). An ABI change, folded into the already-breaking PR.

Notes

Design decision from PR #1 review, and the frame for the partiallyFillable stranding fix. Handlers being unaffected is evidence the fill half was never load-bearing for them.

[mfw78]

Settling the shape so implementation can proceed:

/// Handler-facing: what poll() returns. Handlers can only ever produce these.
enum GeneratorResultCode { POST, WAIT_TIMESTAMP, WAIT_BLOCK, TRY_NEXT_BLOCK, INVALID }

struct GeneratorResult {
    GeneratorResultCode code;
    GPv2Order.Data order;      // valid iff code == POST
    uint256 nextPollTimestamp; // POST: 0 = validTo+1, max = final order
    uint256 waitUntil;         // WAIT_*: timestamp or block
    string reason;
}

/// Registry-facing: composed by ComposableCoW, never by handlers.
enum FillStatus { NONE, PARTIALLY_FILLED, FILLED, INVALIDATED }

struct PollResult {
    GeneratorResult generator;
    FillStatus fill;
    uint256 filledAmount;
}

Composition rules (ComposableCoW):

• fill derives from settlement.filledAmount(uid): 0 → NONE; type(uint256).max → INVALIDATED (distinguishes invalidateOrder from a genuine fill — fixes polling: overlay mislabels invalidateOrder'd orders as FILLED #11); >= target → FILLED; else PARTIALLY_FILLED.
• Verdict and fill are orthogonal: POST + PARTIALLY_FILLED coexist and the signature is still returned for partiallyFillable orders — fixes the stranding in settlement: fill overlay strands the remainder of a partiallyFillable order #10.
• checkOrder returns the same composed PollResult — fixes polling: checkOrder reports SUCCESS on a filled order (skips the fill overlay) #9.
• Signature emitted iff generator.code == POST and fill is NONE, or PARTIALLY_FILLED with partiallyFillable.

Handlers lose the two unreachable variants and the dead filledAmount field; all five order types are otherwise untouched. #9, #10, #11 are linked as sub-issues and land with the same slices.

[mfw78]

Amendment: the reason field landed as bytes4 reasonCode — the selector of a handler-declared custom error — so the whole error surface is typed; full inner revert data (Panic sub-codes, error arguments) is retrievable via tryGenerateOrder.