IngestCheckpoint

How far an ingest got, and the only thing needed to carry on from there.

acknowledgedPoints is a count rather than a cursor because that is what can be honoured against an arbitrary Flow: a source is replayed from the beginning and the first acknowledgedPoints are skipped. It follows that resuming is only correct if the source emits the same points in the same order on the second run. A query over a stable table is; a directory listing whose order depends on the filesystem is not, and neither is a stream that skips what a previous run consumed.

lastPointId is carried so a caller can check that assumption instead of assuming it: re-run the source, take the point at index acknowledgedPoints - 1, and if its id is not this one, the source is not replaying and the token does not apply to it.

The count only advances over an unbroken prefix. With batches in flight at once, a later batch can be acknowledged while an earlier one is still being retried, and counting that as progress would mean resuming past points the server never wrote.

It is a lower bound, and that is the safe direction

The collection may hold more than this token claims. When a run is killed, the batches that were in flight are cancelled where they stand, and the server may already have applied one of them: the request was sent, the acknowledgement never came back, and an acknowledgement that never arrived cannot move a checkpoint.

So resuming from a token re-sends a few points that are already there. Upsert is keyed by point id, so writing the same point twice leaves the same collection, which is what makes the overlap free. The opposite arrangement, a token that could claim more than the server has, would skip points and lose them silently, and there is no cheap way to notice.