Module observation 

Partial materialization / observation views (Phase 7.3).

materialize_observation serves a narrow byte range of the reconstructed source from a parsed descriptor that carries an observation index. It is a view API: the complete-materialization path (crate::materialize::materialize) is unchanged and remains the authority for whole-source exactness.

Decline, never guess

A descriptor without an index is declined with ErrorClass::UnsupportedFeature; the function never silently falls back to full materialization, so a reported cost is never a whole-file cost in disguise.

Op selection: linear skipping vs. a bounded prefix

The op layout is re-derived from the program with Program::analyze_ops (the index’s op table is advisory; the program is authoritative). Let the requested output range be [a, b).

• If every op is a linear, independent block producer — one of Op::EmitObject, Op::Inline, Op::DecodeChannel, Op::DeflateReplay, or Op::InterleaveChannels — then each op’s output is a pure function of its own inputs and its absolute start offset. Only the ops whose output intersects [a, b) are evaluated; ops entirely before a are skipped (no bytes produced, no channel decoded).
• Otherwise (the program uses any position-dependent op: Op::RepeatLast, Op::MarkOffset, Op::EmitOffset, Op::PackSegments, or Op::PackedChannels) the ops 0..=last are evaluated as a prefix. This is correct but can produce up to the whole document; it is the honest fallback. ObservationStats::work_amplification reports how much of the program was walked.

Lazy entropy-channel decoding

Only the entropy channels referenced by the evaluated ops are decoded; the complete path in crate::materialize still decodes every channel. A referenced channel is decoded in full, so the conversion-contract tail check is preserved for exactly the channels that are used. Objects are already resident in the descriptor, so “fetched” here means “read by an evaluated op”.

descriptor_bytes_traversed is an approximation

This in-memory path parses the whole framed descriptor into memory, so it has no true I/O seek accounting. ObservationStats::descriptor_bytes_traversed reports the sum of the serialized record payload lengths the path needed — the graph record, the referenced object payloads, the referenced channel payloads, and the index record — as a documented CPU-side approximation, not a byte-read figure. The referenced channel payloads are already included here, so ObservationStats::entropy_bytes_decoded is a subset of descriptor_bytes_traversed and the two fields must never be summed. This path reports bytes_read == 0 (it performs no I/O of its own); the seek reader (crate::materialize::seek::materialize_observation_seeked, Phase 8) reports a real, instrumented bytes_read while sharing this path’s op selection and evaluation verbatim.

A partial view — in-memory or seeked — is an observation: it serves bytes consistent with the descriptor’s own validated program/index/directory, but it never recomputes the whole-source SHA-256, so integrity_verified is false. Only materialize/decode/verify are the archival authority.

Structs

ObservationReport

A served observation: the exact requested bytes plus its cost attribution.

ObservationStats

Cost attribution for one observation.

Enums

ObservationSelector

A narrow observation of the reconstructed source.

Functions

materialize_observation

Serve one observation from a parsed descriptor carrying an observation index.