SegmentObserver

A listener on the documents that pass through segment writing.

This is the hook the modelling and indexing layers hang off, and it exists because flush and compaction already walk every document. Statistics gathered on a pass the engine is making anyway cost the walk, not a scan — which is the whole reason "model later" is cheap here rather than a batch job somebody has to schedule.

It is declared in rabosh-core and implemented above it. Dependencies flow strictly downward, so the core cannot know what a catalog or an index is; what it can do is say when a document is being written and to which segment, and let the layer that cares decide what to keep.

What an implementation may assume. Calls for one segment are made on one thread, in key order, between one beginSegment and the matching SegmentObservation.complete or SegmentObservation.abandon. Several segments may be in flight at once — a compaction cuts its output into more than one file — so per-segment state must live in the SegmentObservation, not in the observer.

What an implementation must not do. Block for long, or throw. A failure in derived data must not take down the engine, so a callback that throws abandons that segment's observation and is reported to observerFailed; the write itself carries on. An observer that would rather be fatal says so by throwing from observerFailed, which does propagate.