# Postures and work splits

A posture is an intent; `plan_split` resolves it into a `WorkSplit`.

## Postures

| Posture         | Device share                 | Needs                                                       |
| --------------- | ---------------------------- | ----------------------------------------------------------- |
| `cpu`           | 0.0                          | nothing                                                     |
| `offload`       | 1.0                          | nothing; a speedup is reported if both costs are given      |
| `collaborative` | the balance point, see below | `cpu_seconds` and `device_seconds`, or `profile` and `rows` |
| `adaptive`      | refused with `PostureError`  | a plan boundary, not a row share; planned where the plan is |

`offload` minimizes host occupancy, not wall time: it costs speedup against
`collaborative` and buys back the whole host.

## The balance point

With a whole-query time for each engine and a per-job fixed cost for the
device, the collaborative share solves

```
(1 - s) * cpu = fixed + s * device
```

so `s = (cpu - fixed) / (cpu + device)` and both arms finish together. When no
share beats the host alone, because the fixed cost is already most of the host
time, the result is a `cpu` split whose rationale says so.

## `WorkSplit`

| Field               | Meaning                                                                          |
| ------------------- | -------------------------------------------------------------------------------- |
| `posture`           | the posture that produced it, which may be `cpu` after a collaborative refusal   |
| `device_share`      | the fraction of rows the device arm takes, from the start of the table           |
| `rationale`         | one sentence saying where the share came from                                    |
| `predicted_speedup` | wall time of the host alone over the predicted wall time, or `None` when unknown |

`WorkSplit.check()` re-runs the invariants; every consumer calls it, because
`model_copy` does not validate.

## Batches

`batch_count(payload_bytes, resident=..., knee_bytes=...)` says how many batches
one engine's share is delivered in. Batching hides the transfer behind the
compute, so resident data gets one batch and a streamed payload gets the count
that keeps each batch above the link's measured transfer knee, rounded down.
The knee is a property of the link and is measured, so there is no default.

## Errors

`PostureError` is raised for an unknown posture, a collaborative request with
no costs, a non-positive estimate, or the adaptive posture.