InputCapability::time() requires TotalOrder and returns Option

[frankmcsherry]

Since #813 a message's stamp is a multiset of timestamps, and InputCapability::time() panicked unless the stamp was a singleton. This turns that runtime failure into a compile-time one.

The change. InputCapability::time() is replaced by least(), which exists only for T: TotalOrder, where every non-empty stamp has a least element, and returns Option<&T>: the least element, or None exactly when the message was stamped by no capabilities (it makes no progress claims). retain(port) is replaced by retain_least(port), returning Option<Capability<T>> likewise, and the Deref to T is gone. Partially ordered timestamps must read stamp() and forward its elements with retain_stamp(), which is unchanged. Stamp::least() is the underlying accessor. The names say what is computed, and no existing time() or retain() call site silently inherits new behavior: each one fails to compile and is pointed at least, retain_least, or retain_stamp.

An operator that needs a time asks for it with an if let, and a message with no capabilities is dropped. That is a decision, not an accident: such a message makes no progress claims and may arrive after the frontier has passed every time in its contents, so an operator whose work is keyed by time has nothing to do with it.

input.for_each_stamp(|cap, data| {
    if let Some(cap) = cap.retain_least(output.output_index()) {
        stash.entry(cap.time().clone()).or_default().extend(...);
        notificator.notify_at(cap);
    }
});

Operators. Those whose logic reads one time from the capability are bounded by TotalOrder and use the idiom: count/accumulate, aggregate, state_machine, delay, delay_batch, branch, and branch_when. For total orders they behave exactly as before; for partial orders they no longer compile, which is deliberate: they use the capability as a stand-in for a time the records do not carry, and there is no correct generalization of that to a message stamped by several times. (An earlier draft keyed their stashes by stamp and flushed once every element completed; that stalls in a loop whenever a pointwise boundary map produces comparable elements, so it was dropped.) The bound is the static property "at most one meaningful time"; it makes holding capabilities sound, and does not give these operators meaning for a multi-element stamp. They have no users in differential-dataflow or Materialize and will be removed in a follow-up PR.

Inspect is one trait with two methods, neither bounded: inspect_core observes every container with its stamp and every frontier change, and inspect observes records. inspect_batch, inspect_time, inspect_container, and the InspectCore trait are removed; each revealed one time, and each is a map inside inspect_core. reclock is rewritten to stash by stamp and notify at each clock element, releasing data once some element of its stamp is at or before the clock time; a message with no capabilities could never be released and is discarded. It needs no bound. The book is updated to the new names.

Rename. for_each_time is now for_each_stamp: containers are grouped by the stamp of their message, not by a time, and the closure receives a capability for that stamp. Closure arguments named time are renamed cap throughout the docs and examples; they were never a time. for_each_time remains as a deprecated alias.

Breaking changes. InputCapability::time() and retain() are removed in favour of least() and retain_least(), with a TotalOrder bound and Option results; Deref for InputCapability is removed, so implicit uses (*cap, cap.less_equal(..)) become explicit; the operators above gain a TotalOrder bound; Debug for InputCapability prints the stamp. Examples and doctests are adapted; the loop_variable doctest terminates by data rather than by branch_when, which now needs a total order.

Verification. All unit, integration, and 155 doctests pass. A differential-dataflow adaptation (eight files: capture, upsert, half_join, Collection::delay reimplemented without delay_batch, diagnostics, two tests) builds and passes its workspace tests against this branch and will follow as its own PR once this lands.

🤖 Generated with Claude Code

https://claude.ai/code/session_012k2GSwxmvD2LvckkoXi6GK