Module seek 

Seek-based partial materialization (Phase 8.2).

materialize_observation_seeked serves the same narrow byte range as crate::materialize::observation::materialize_observation, but from a Read + Seek source and by reading only the records the query needs. It does this by reading the optional DIRECTORY record (written as the first record at offset 64), which locates every record class, and then seeking directly to the GRAPH, OBSERVATION_INDEX, INTEGRITY, and the referenced OBJECT/ENTROPY_CHANNEL/MODEL records.

Decline, never guess

A descriptor whose header does not advertise the seek feature, or whose first record is not a DIRECTORY, is declined with crate::ErrorClass::UnsupportedFeature; the reader never silently falls back to reading the whole file. Op selection, lazy channel decoding, and the evaluated slice are shared verbatim with the Phase-7 in-memory path ([crate::materialize::observation::select_ops] / serve_selection), so the two readers cannot diverge.

The directory is advisory, never authority

Every locator is cross-checked against the record it points at (tag byte and payload length), every record’s own CRC32C is verified when it is read, the directory’s internal geometry is validated by SeekDirectory::validate_structural, and the ObservationIndex is re-derived against the directory-derived object/channel lengths with ObservationIndex::validate. A lying directory is rejected, never trusted.

Integrity is honest

A partial read cannot recompute the whole-source SHA-256, so a served slice is an observation consistent with the descriptor’s own validated program/index/directory — not a verified archival read. The returned ObservationStats carries integrity_verified == false and a real bytes_read measured by the internal CountingReader. Only materialize/decode/verify check INTEGRITY and are the archival authority.

Structs

CountingReader

A Read + Seek wrapper that counts the bytes actually returned by read and the number of read/seek calls.

Functions

materialize_observation_seeked

Serve one observation from a seekable .voldoc source by reading only the records the query needs.